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Preface 



Machine language is the native language of the Amiga and allows the 
programmer to take complete advantage of the Amiga's capabilities and 
speed. 

Programming the Amiga in machine language requires knowledge of the 
MC68000 processor and the internal characteristics of the Amiga. The 
large number of functions offered by the Amiga's operating system 
should be accessible and usable by the machine language programmer. 

Accessing the Amiga's operating system has been difficult for the 
machine language programmer. The Amiga's documentation is written for 
the C-programmer, and is not much help to the machine language pro- 
grammer. In this book we will introduce you to the Amiga's processor, 
the operating system and how to access them using machine language. 

First we'll take a look at memory organization and the basic operations of 
the computer. Next we'll take a more detailed look inside the Amiga and 
its 68000 processor. Sample programs will allow you to program the 
Amiga's 68000 processor while learning about it. 

After the tour of the 68000 processor we'll show you how you can create 
windows and menus. The sample programs will allow you to build a 
library of machine language routines. You can use these routines to create 
fast, user friendly, professional programs. 

We hope you'll enjoy applying the knowledge you will soon gain from 
this book in your own programs and experiments. 

Stefan Dittrich Gummersbach April 1987 
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1 . Introduction 



Before you tackle machine language, you should take a closer look at 
several things that are vital to machine language programming. 



1.1 Why machine language? 



Machine language is actually the only language the MC68000 processor 
understands. All other languages, such as BASIC, Pascal or C, must first 
be translated (interpreted or compiled) into machine code. This process can 
take place either when the program is executed (the BASIC interpreter), or 
before program execution (the Pascal and C compilers). 

Advantages The great advantage of machine language over an interpreted and compiled 

program is machine language programs are faster. With an interpreter like 
BASIC, each line must first be interpreted before it is executed, which 
requires a great deal of time. A Pascal or C compiler translates the source 
code into machine language. This translation procedure does not produce 
programs that are as fast as a pure machine language program. 

Another advantage machine language has over BASIC is that an inter- 
preter is not needed for the execution of a machine language program. 

Machine language can access all the capabilities of the computer since it 
is the language native to the computer. It is possible that machine 
language subroutines are required by a higher level language to access 
functions that aren't directly accessible by that language. 
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1.2 A look into the Amiga's memory 



Before a machine language program can be written, you must know 
exactly what the program is required to do. You must also be aware of 
what resources are needed and available to achieve those goals. The most 
important of these resources is the memory in the Amiga. 



1.2.1 



RAM, ROM, hardware register 



Random Access Memory, referred to as RAM, allows information to be 
placed in it and then withdrawn at a later time. This memory consists of 
electronic components that retain data only while the computer is turned 
on (or until a power-failure). 

So that the computer is able to do something when it is first turned on, 
such as prompting for the WorkBench or Kickstart disk, a program has to 
remain in memory when the power is off. A memory type which can 
retain data without power is needed. This second memory type is known 
as ROM. 



ROM 



PROM 



ROM stands for Read Only Memory, indicating that data can only be read 
from this memory, not written to it. The Amiga contains a ROM, that 
loads the Workbench or Kickstart disk into RAM. The first version of the 
Amiga did not contain the Kickstart in ROM. 

One variation of ROM is the PROM, or Programmable Read Only 
Memory. This special type of ROM can actually be programmed once. 
Since it cannot be erased once programmed, it isn't encountered very of- 
ten. More often you'll see EPROM's, or Erasable Programmable ROM's. 
These special chips, which can be erased with ultraviolet light, have a 
little window on the surface of the chip usually covered by tape. 



EEROM Although not available on the consumer market and much more expen- 

sive than RAM, the EEROM (Electrically Erasable ROM) offers another 
alternative to programmable ROM. These chips function like RAM, 
except that information is not lost when the power is turned off. 
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WOM 



Registers 



With the birth of the Amiga, another type of memory, WOM, was 
created. This particular type of memory is Write Once Memory. The 
Kickstart disk is read into this memory when the computer is first booted. 
After this, no more data can be read into that memory. Actually this isn't 
a completely new component, but simply RAM that is locked once data 
has been read into it, after which the data can only be read from that 
memory. 

In addition to RAM and these variations of ROM there is another type of 
memory situated between those two groups. This memory is connected to 
the processor through a group of peripheral controllers. Thus it is com- 
monly referred to as the hardware register, since the computer's hardware 
is managed by this system. We'll go into greater detail on how to use 
these hardware registers later in this book. 

Let's take a closer look at the structure and use of the memory most 
familiar to us all, RAM. 



1.2.2 Bits, bytes, and words 

Kilobyte The standard size in which memory is measured is a kilobyte (Kbyte). 

One kilobyte consists of 1024 bytes, not 1000 as you might expect. This 
unusual system stems from the computer's binary mode of operation, 
where numbers are given as powers of 2, including kilobytes. 

To access a memory block of one kilobyte, the processor requires 10 
connections which carry either one volt or zero volts. Thus 2 A 10=1024 
combinations or 1024 bytes of memory, are possible. 



Byte 



A byte, in turn, consists of yes/no, on/off information as well. A byte 
can be one of 2 A 8 different values, and thus it can represent any one of 
256 numbers. The individual numerical values that make up a byte, 
which also are the smallest and most basic unit encountered in any com- 
puter, are called bits (short for binary coded digit). 



A 512 Kbyte memory, such as the Amiga's, contains 2 A 19=524288 bytes 
and 4194304 bits. It may seem unimaginable, but a memory of that size 
has 2 A 4 194300 different combinations. 
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Word Back to the basics.. .bits and bytes are sufficient to program an eight bit 

processor like the 6500, since it can work only with bytes. To program a 
16/32 bit processor like the Amiga's MC68000, you'll need to know two 
new data forms: words, consisting of 16 bits (the equivalent of two 
bytes), and long words, which are 32 bits (the equivalent of 4 bytes or 2 
words). 

A word can be any number between and 65536, a long word can be to 
4294967295. The MC68000 processor can process these gigantic num- 
bers with a single operation. 

Once in a while you need to use negative numbers as well as positive 
ones. Since a bit can only be 1 or and not -1, an alternate system has 
been adopted. If a word is to have a specific sign, the highest value digit 
or 15th bit in the word (positions are always counted from zero) deter- 
mines the sign of the word. With this method words can carry values 
from -32768 to +32768. One byte can range from -127 to +127. In a 
byte, the value -1 is given by $FF; in a word it's $FFFF, -2 is $FE 
($FFFE), etc. 

Let's stick with positive values for the time being, to aid in the visual- 
ization of a bit in relation to its bit-pattern. Machine language does not 
use the familiar decimal system. Instead, it commonly employs the 
binary as well as the octal and hexadecimal number systems. 



1.2.3 Number systems 



Let's take a look at the decimal system: its base number is 10. This 
means that every digit represents a power of 10. This means that the 246 
represents 2*10 A 2+4*10 A 1+6*10 A 0. The decimal system offers a selection 
of 10 characters, namely to 9. 

Binary This procedure is different for the binary system. The binary system offers 

only two different characters: 1 and 0. Thus the system's base number is 
two. The decimal value of 1010 would therefore be: 

1*2 A 3+0*2 A 2+1*2"1+0*2 A 0=2 A 3+2 A 1=8+2=10 (in the decimal system) 

Generally binary numbers are identified by having a percentage symbol as 
a prefix. See if you can determine the decimal value of this number: 
%110010... 
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Well, did you get 50? That's the right answer. The most simple method 
to arrive at this result is to simply add up the values of the digits that 
contained a 1. The values of the first eight digits are as follows: 



digit 


8 


7 


6 


5 


4 


3 


2 


1 


value 


128 


64 


32 


16 


8 


4 


2 


1 



Octal The octal system, whose base is eight, is similar. The character set 

consists of the numbers to 7. The decimal equivalent of the octal num- 
ber 31 is: 3*8*1+1*8*0=25. However, the octal system isn't nearly as 
important as the next one... 

The base number of the hexadecimal system is 16, and its character set 
ranges from to F. Thus, A would be the equivalent of a decimal 10, and 
F would be 15. The dollar sign ($) indicates a hexadecimal number. The 
binary and hexadecimal systems are the most important numerical sys- 
tems for assembly language programming. 

Hex The hexadecimal representation of a byte ranging from to 256 always 

has two digits: $00 to $FF. A word ranges from $0000 to $FFFF and a 
long word from $00000000 to $FFFFFFFF. 

It is quite easy to convert binary numbers into hexadecimal: simply split 
up the binary number into groups of four digits. Each of these groups of 
four digits then corresponds to one hexadecimal digit. Here's an example: 

binary number %110011101111 

split up %1100 %1110 %1111 

result $C $E $F 

thus: %110011101111 = $CEF 

The opposite operation is just as easy... 

hexadecimal $E30D 

split up $E $3 $0 $D 

result %1110 %0011 %0000 %1101 

thus: $E30D=%1 11 000 1100 001101 

This method can also be used to convert binary into octal and vice versa, 
except that groups of three digits are used in that case. 

octal number 7531 

split up 7 5 3 1 

result %111 %100 %011 %001 

thus: octal 7531=%111101011001 

This binary number can then be converted into hexadecimal, as well: 
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binary number %111101011001 

split up %1111 0101 1001 

result $F $5 $9 

thus: octal 7531 = $F59 

The following calculation can then be used to convert the number into the 
familiar decimal system: 



hexadecimal 


$F59 


split up 


$F $5 $9 


result 


15*16"2 +5*16 +9 


thus: 


$F59 = 3929 decimal 



Although these conversions are quite simple, they can get to be rather 
annoying. Many assemblers can ease this task somewhat: they allow you 
to enter a value with '?' upon which it returns the value in decimal and 
hexadecimal forms. There are even calculators that perform number base 
conversions. 

Often this conversion has to be performed in a program, for instance 
when a number is entered by the user and then processed by the computer. 
In this case the number entered, being simply a combination of graphic 
symbols, is evaluated and then usually converted into a binary number, in 
effect, a word or a long word. 

This process is often required in reverse order, as well. If the computer is 
to display a calculated value in a specific number system, it must first 
convert that number into a series of characters. In a later chapter you will 
develop machine language routines to solve these problems. You can then 
use these routines in your own programs. First you still have to cover 
some things that are fundamental to machine language programming on 
the Amiga. 
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1 .3 Inside the Amiga 



In order to program machine language, it is not sufficient to know only 
the commands of the particular processor, one must also have extensive 
knowledge of the computer being programmed. Let's take a good look 
inside the Amiga. 



1.3-1 Components and libraries 

The Amiga is a very capable machine, due to the fact that there are 
components that do a large part of the workload, freeing up the 68000 
processor. These are referred to as the "custom" chips, which perform 
various tasks independently of the 68000 processor. 

Custom chips This task force is comprised of three chips, whose poetic names are 
Agnus, Denise and Paula. The main task of Agnus, alias blitter, is the 
shifting of memory blocks, which is helpful for operations such as quick 
screen changes. Denise is responsible for transferring the computer's 
thoughts onto the screen. Paula's tasks consist of input/output jobs, such 
as disk operation or sound. 

These chips are accessed by the processor through several addresses 
starting at $DFF000, which are also known as the hardware registers 
(you'll find more detailed information about the registers in the corres- 
ponding chapter). To simplify the otherwise rather complicated procedure 
of utilizing these chips, several programs have been included in the Kick- 
start and Workbench libraries. These programs can be called by simple 
routines and then take over the operation of the respective chips. 

If only these library functions are used to program the Amiga, the para- 
meters are the same, regardless of the language used. Only the parameter 
notation differs from language to language. BASIC is an exception in this 
respect, since its interpreter translates the program calls, which is why 
you don't need to know how the Amiga executes these functions in order 
to use them. 

The library functions are written in machine language and are thus closely 
related with your own machine language programs. Actually you could do 
without the library programs and write all of the functions yourself. 
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However, the incredible workload of this task is so discouraging, that 
you'd rather stick with the library functions. 



1.3.2 Memory 

First let's look at the RAM of the Amiga 1000. The standard version of 
this computer has over 512 Kbytes of RAM, ranging from the address 
$00000 to $7FFFF, or to 524287. If the memory is expanded to one 
megabyte, the first 512K still starts at address $000000 however the start 
of anything greater than 512K can go anywhere in the address space 
between $200000 to $9FFFFF. With the release of AmigaDOS 1.2, the 
Amiga figures out where to put memory expansion by using a special 
'Autoconfig' scheme. This allows you to add memory and I/O without 
worrying about addresses and dip switches. 

Chip RAM The chips that support the Amiga's processor access RAM almost totally 

independently and thus ease the workload of the processor. However, there 
is a drawback: these chips can only access the first 512K bytes of RAM. 
Thus, graphics and sound data handled by these chips must be stored in 
this memory range. Because of this, that memory range is referred to as 
chip RAM. 

Fast RAM The counterpart to chip RAM is the remaining RAM which, if the com- 

puter is equipped with it, begins at $200000. Since only the processor 
itself has access to this part of memory it is known as fast RAM. 

Here's an overview of the Amiga's memory : 

$000000-$07FFFF chip RAM 

$080000-$lFFFFF reserved 

$200000-$9FFFFF potential fast-RAM 

$A00000-$BEFFFF reserved 

$BFD000-$BFDF00 PIAB (even addres ses ) 

$BFE001-$BFEF00 PIA C (odd addresses ) 

$C00000-$DFEFFF reserved for expansion 

$DFF000-$DFFFFF custom chip registers 

$E00 000-$E7FFFF reserved 

$E80000-$EFFFFF expansion port s 

$F00000-$F7FFFF reserved 

$F80000-$FFFFFF system ROM 

Since the Amiga is multi-tasking, when a program is loaded into mem- 
ory, it is simply loaded into any memory location. The memory range 
thus occupied is added to a list of occupied memory and the memory range 
is then considered barred from other uses. If another program is loaded, 
which is quite possible with the Amiga, it is read into another memory 

10 
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location which is then marked on the occupied list. If the first program 
should require additional memory, to use a text buffer for example, that 
memory first has to be reserved. Otherwise another program could acci- 
dentally be loaded into the memory needed for this task. 

What's interesting about this procedure is that when the first program 
loaded has ended, the memory occupied by it is freed for further use. As a 
result, RAM is then chopped up into occupied and free parts, which are 
no longer related to each other. The Amiga can still utilize these chunks 
of memory as if they were one continuous chunk. After all, parts is parts. 
An example of this is the dynamic RAM disk which is always available 
under the name RAM:. 

This RAM disk is actually quite a phenomenon, since it is always 
completely filled. If a program is erased from RAM disk, the memory 
allocated to that program, regardless of its location and structure, is given 
back to the system. Thus, if you reserve and fill 100 Kbytes of memory, 
it would be quite possible that the 100 Kbytes actually consist of various 
pieces of memory independent of one another. You never notice this since 
the Amiga automatically corrects the difference between apparent and 
actual memory. 



1.3.3 Multi-tasking 



The Amiga is truly an amazing machine, being capable of doing several 
things at one time. A red and white ball might be bouncing around in one 
window while you're working on text in another window and watching a 
clock tick away in a third. 

At least that's the impression most people get when they receive their 
first Amiga demonstration. However, there is a catch to this: even the 
Amiga has only one processor, which can really only do one thing at a 
time. 

The tricky part is when more than one program is running, each program 
is executed part by part, and the Amiga is constantly switching from one 
program back to the other program. In the example above, the ball would 
first be moved by one pixel, then the processor would check for a text 
entry and if necessary display it, after which it would move the clock's 
second hand. This procedure would be repeated over and over, as the three 
programs are executed together. The problem is, that the greater the work- 
load on the processor, the slower things happen. Thus, programs run 
slower during heavy multi-tasking. 
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Tasks Each of these jobs that the Amiga has to execute are commonly referred 

to as tasks. ..thus, multi-tasking. During multi-tasking, each task is 
assigned a special time segment during which that particular task is 
executed. These time segments can be controlled, so that more time- 
consuming programs can be allotted somewhat more processing time. 

The programmer actually doesn't need to know how this time slicing 
works. You can write a program without paying any attention to multi- 
tasking and then run it simultaneously with another program running in 
the background. The only restriction is that you'll have to start the 
program either from the CLI with 'run', or from the Workbench. If you 
execute the program from the CLI by simply typing its name, the pro- 
cessor allots all the time it can get from the CLI to that program, until 
the execution is complete. Starting the program with 'run' frees the CLI 
for other uses while the program is being executed. 

There is another restriction regarding multi-tasking that applies to assem- 
bler programmers. Aside from the use of extra memory, which must first 
be reserved, the hardware registers should not be directly accessed. Instead, 
the library functions should be used. The reason for this is quite simple: 

Should you, for instance, specify the printer port as the input line and are 
reading data in, another task might suddenly think it's supposed to be 
printing. The line would thus be switched to output and data would be 
written out. After this, your program would try to read more data in, 
which would not be possible. 

This is an oversimplified example, but it points out the problem never- 
theless. In real programming situations the effects of multiple direct 
programming of the hardware registers can be much more catastrophic. If 
your program still needs to access the hardware registers directly (which 
can have some advantages), then make sure that the program always runs 
by itself. 
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2. The MC68000 processor 



The Amiga's MC68000 processor is a 16/32 bit processor, which means 
that while it can process data of 32 bits, it "only" has a 16 bit data bus 
and a 24 bit address bus. Thus, it can access 2 A 24= 167772 16 bytes (or 16 
Mbytes) of memory directly. 

7.1 megaherz The Amiga 68000 processor, running at 7.1 megaherz, is quite fast, 
which is required for a computer with a workload as heavy as the 
Amiga's. The Amiga also possesses a number of custom chips that great- 
ly ease the workload of the processor. These custom chips manage sound, 
in/output, graphics and animation, thus freeing the processor for calcula- 
tions. 



2.1 Registers 



In addition to the standard RAM, the processor contains internal memory 
called registers There are eight data registers (D0-D7), eight address 
registers (A0-A7), a status register (SR), two stack pointers, a user stack 
pointer, a system stack pointer (USP and SSP) and the program counter 
(PC). 

Register Sizes The data registers, the address registers, and the program counter are all 32 
bits, while the status register is 16 bits. These registers are located 
directly in the processor so they aren't accessed the same way memory 
would be accessed. There are special instructions for accessing these 
registers. 

Data Registers The data registers are used for all kinds of data. They can handle opera- 
tions with bytes (8 bits), words (16 bits) and long words (32 bits). 

Address The address registers are used for storing and processing addresses. This 

Registers way they can be used as pointers to tables, in which case only word and 

long word operations are possible. 
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Stack pointer The address register A7 plays a special role: this register is utilized as the 
Stack Pointer (SP) by the processor, and thus is not recommended for 
normal use by the programmer. Which of the two possible stacks is 
being pointed to depends on the present mode of the processor, but more 
about that later. 

This stack, to whose actual position the stack pointer is pointing, is used 
to store temporary internal data. The stack works similar to a stack of 
notes on your desk: the note that was added to the stack last is the first 
one to come off of the stack. This type of stack is known as LIFO (Last 
In, First Out). There is another type of stack, the FIFO (First In, First 
Out) which is not used by the processor itself. 

How these registers and the SP can be manipulated, or how to work with 
the stack, is presented in the next chapter. Let's continue with the regis- 
ters for now. 

Status Register The Status Register (SR) plays an important role in machine language 
programming. This 16-bit quanity (word) contains important information 
about the processor status in 10 of its bits. The word is divided into two 
bytes, the lower byte (the user byte) and the upper byte (the system byte). 
The bits that signify that certain conditions are referred to as flags. This 
means that when a certain condition is present, a particular bit is set. 



The user byte contains five flags, which have the following meanings: 

Bit Name Meaning 

Carry bit, modified by math calculations, and 
shift instructions. 

Similar to carry, indicates a change of sign, in 
other words, a carry from bit six to bit seven. 
Bit is set when the result of an operation is 
zero. 

Is set when the result of an operation is nega- 
tive. 

Like carry, is set for arithmetic operations, 
not used 






(C, Carry) 


1 


(V, Overflow) 


2 


(Z,Zero) 


3 


(N, Negative) 


4 
5-7 


(X, Extended) 
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The system byte contains five significant bits: 
Bit Name Meaning 



8 


10 


9 


11 


10 


12 


11 




12 




13 


(S, Supervisor) 


14 




15 


(T, Trace) 



Interrupt mask. Activates interrupt levels 

to 7, where is the lowest and 7 is the 

highest priority. 

not used 

not used 

This bit indicates the actual processor mode 

(0=User, l=Supervisormode). 

not used 

If this bit is set, the processor isin single step 

mode. 



Here's an overview of the status word: 

bit : 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 
name: T-S--I2I1I0---XNZVC 

Don't let the new terms, like mode and interrupt confuse you. We'll talk 
about these in greater detail in the chapter dealing with the operating 
conditions of the processor. 
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2.2 Addressing memory 



In the standard Amiga 500' s and 1000' s the processor has over 512 
Kbytes of RAM available. The Amiga 2000 has one megabyte of RAM 
that can be accessed by the processor. How does the processor access all 
this memory? 

If you're programming in BASIC you don't have to worry about memory 
management. You can simply enter MARKER%=1, and the value is 
stored in memory by the BASIC interpreter. 

In assembler, there are two ways of accomplishing this task: 

1) Store the value in one of the data or address registers, or 

2) Write it directly into a memory location. 

To demonstrate these two methods let's get a little ahead and introduce a 
machine language instruction, which is probably the most common: 
MOVE. As its name states, this instruction moves values. Two parameters 
are required with the instruction: source and destination. 

Let's see what the example from above would look like if you utilize the 
MOVE instruction... 

1) MOVE #1,D0 

This instruction moves the value 1 into data register DO. As you can see, 
the source value is always entered before the destination. Thus, the in- 
struction MOVE D0,#1 is not possible. 

2) MOVE #1, $1000 

deposits the value 1 in the memory location at $1000. This address was 
arbitrarily chosen. Usually addresses of this form won't be used at all in 
assembler programs, since labels that point to a certain address are used 
instead. Thus, the more common way of writing this would be: 

MOVE #1, MARKER 

marker:dc.w l 
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These are actually two pieces of a program: the first part executes the 
normal MOVE instruction whose destination is 'MARKER'. This label is 
usually defined at the end of the program and specifies the address at 
which the value is stored. 

The parameter DC.W 1 is a pseudo-op, a pseudo operation. This means 
that this isn't an instruction for the processor, but an instruction for the 
assembler. The letters DC stand for 'DeClare' and the suffix .W indicates 
that the data is a Word. The other two suffix alternatives would be .B for 
a Byte (8 bits) and .L for a Long word (32 bits). 

This suffix (.B .W or .L) is used with most machine language instruc- 
tions. If the suffix is omitted, the assembler uses .W (word) as the default 
parameter. If you wanted to use a long word, you'd use an instruction that 
looks something like this: MOVE.L #$12345678, DO whereas an 
instruction like MOVE.B #$12, DO would be used for a byte of data. 
However, with this instruction there's one thing you must be aware of... 

Caution: If the memory is accessed by words or long words, the address must be 

even (end digit must be 0,2,4,6,8, A,C,E)! 

Assemblers usually have a pseudo-op, 'EVEN' or 'ALIGN', depending on 
the assembler, that aligns data to an even address. This becomes necessary 
in situations similar to this: 



VALUEl: DC.B 1 
VALUE2: DC.W 1 

If the VALUEl is located at an even address, VALUE 2 is automatically 
located at an odd one. If an ALIGN (EVEN) is inserted here, a fill byte (0) 
is inserted by the assembler, thus making the second address even. 



VALUEl: DC.B 1 

ALIGN 

VALUE2: DC.W 1 

Back to the different ways of addressing. The variations listed above are 
equivalent to the BASIC instruction MARKER% = 1 where the % symbol 
indicates an integer value. 

Let's go a step further and translate the BASIC instruction 
MARKER%=VALUE% into assembler. You've probably already guessed the 
answer, right? 
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MOVE VALUE,MARKER 



marker: dc.w i 

value: dc.w i 

In this case, the contents in the address at VALUE are moved into the 
address at MARKER. 

With the help of these simple examples, you've already become familiar 
with four different ways of addressing, in other words, ways that the 
processor can access memory. The first is characterized by the number 
sign (#) and represents a direct value. Thus, this method is also known as 
direct addressing, and is legal only for the source parameter! 

A further method in which a direct address (in our case, 'MARKER' and 
'VALUE') can be specified, is known as absolute addressing. This method 
is legal for the source parameter as well as for the destination parameter. 

This method can be divided into two different types, between which the 
programmer usually doesn't notice a difference. Depending on whether the 
absolute address is smaller or larger than $FFFF, in other words if it 
requires a long word, it is called absolute long addressing (for addresses 
above $FFFF) or otherwise absolute short addressing. The assembler 
generally makes the distinction between these two types, and thus only 
general knowledge of absolute addressing is required. 

The fourth method of addressing that you've encountered so far is known 
as data register direct. It was the first one introduced (MOVE #1,D0) in 
conjunction with direct addressing, the only difference being that this type 
accesses a data register (such as DO). 

These four methods aren't the only ones available to the 68000 processor, 
in fact there are a total of 12. One other variation called address register 
direct, is almost identical to data register direct, except that it accesses the 
address register instead of the data register. Thus, you can use MOVE.L 
#MARKER,A0 to access address register A0 directly. 

You now know of five ways to address memory with which quite a bit 
can be accomplished. Now, let's tackle something more complicated and 
more interesting. 

Let's take another example from BASIC: 

10 A=1000 

20 POKE A,l 
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In this example the first line assigns the value 1000 to the variable A. 
This can be done in assembler as well: MOVE.L #10 0, A 0. In the as- 
sembler version the absolute value of 1000 is stored in the address register 
A0. 

Line 20 doesn't assign a value to the variable A itself, but rather to the 
memory location at the address stored in A. This is an indirect access, 
which is quite easy to duplicate in assembler: 

MOVE.L #1000,A0 Jbring address in A0 

MOVE #1,(A0) ;write 1 into this address 

The parentheses indicate an addressing method known as address register 
indirect. This method works only with address registers, since a 'data 
register indirect' does not exist. 

There are several variations of this method. For instance, a distance value 
can be specified, which is added to the address presently located in the 
address register before the register is actually accessed. The instruction 
MOVE #1,4 (A0 ) , if applied to the example above, writes the value 1 
into the memory cell at 1000+4=1004. This distance value can be 16 bits 
long and can be positive or negative. Thus, values from -32768 to 
+32768 are accepted. This specific variation of addressing is called address 
register indirect with a 16 bit displacement value. 

There is another very similar variation: address register indirect with an 8 
bit index value. While this variation is limited to 8 bits, it also brings 
another register into play. This second register is also a distance value, 
except that it is a variable, as well. 

We'll try to clarify this with an example. Let's assume that a program 
includes a data list that is structured like this: 



RECORD: DC.W 2 Jnumber of entries-1 

DC.W 1,2,3 Jelements of list 

We'll use MOVE.L #RECORD,A0 to load the list into the address register 
A0. Then you can use MOVE (AO ) ,D0 to pull the number of elements in 
the list into the data register. To access the last element of the list only 
one instruction is needed. The whole thing looks something like this: 

CLR.L DO ;erase DO completely 

MOVE.L #RECORD,A0 ;address of list in A0 

MOVE (A0),D0 jnumber of elements-1 in DO 

MOVE 1(A0,D0),D1 ;last element in D 1 

RECORD: DC.W 2 jnumber of entries-1 

DC.W 1,2,3 jelements of list 
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This last instruction accesses the byte that is located at 1+A0+D0, in 
other words, the record +1 where the data begins plus the contents of DO 
(in this case 2). 

This method of accessing is very useful. It works exquisitely for the 
processing of tables and lists, as the example demonstrates. If no distance 
value is needed, simply use a distance value of zero, which some assem- 
blers automatically insert as the default value if, for instance, only MOVE 
(A0,D0) is entered. 

The latter two methods have a third variation, which has its own charac- 
teristic trait. It doesn't utilize an address register, but uses the Program 
Counter (PC) instead. The program counter with displacement method 
proves useful when a program must function without any changes in all 
address ranges. The following two statements (in the 15 bit limits) have 
the same effect: 

MOVE MARKER,D0 

and 

MOVE MARKER (PC), DO 

This method is actually rather imprecise, since the first instruction spec- 
ifies the actual address of the marker with MARKER, while the second line 
specifies the distance between the instruction and the marker. However, 
since it would be quite cumbersome to constantly calculate the distance, 
the assembler takes this task off our hands and calculates the actual value 
automatically. 

Let's examine the difference between the two instructions. In a program 
they'll accomplish the same thing, although they are interpreted as two 
completely different things by the assembler. You'll assume a program 
begins at the address $1000 and the marker is located at $1100. The 
generated program code then looks something like this: 

$001000 30 39 00 00 1100 MOVE MARKER,D1 

or 

$001000 30 3A00FE MOVE MARKER (PC) ,D1 

As you can see, the generated code of the second line is two bytes shorter 
than the first line. In addition, if you were to shift this code to the address 
$2000, the first version still accesses memory at $1100, while the second 
line using the PC indirect addressing accesses memory at $2100 correctly. 
Thus, the program can be transferred to almost any location. 
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This, then, is program counter with 16 bit diplacement value. As we 
mentioned, there is also program counter with an 8 bit index value, which 
permits a second register as a distance value, also known as an offset. 

There are two more addressing modes left. These two are based on indirect 
addressing. They offer the capability of automatically raising or lowering 
the address register by one when memory is accessed with address register 
indirect 

To automatically increase the register, you'd use address register indirect 
with post-increment. The address register raises this by the number of 
bytes used AFTER accessing memory. Thus, if you write 

MOVE.L #1000,A0 
MOVE.B #1,(A0) + 

the 1 is written in the address 1000 and then A0 is raised by one. Instruc- 
tions like this are very helpful when a memory range is to be filled with a 
specific value (for instance when the screen is cleared). For such purposes 
the instruction can be placed in a loop.. .which we'll get to later. 

The counterpart to post-increment is address register indirect with pre- 
decrement. In this case the specified address register is lowered by one 
BEFORE the access to memory. The instructions 

MOVE.L #1000,A0 
MOVE.B #1,- (A0) 

writes 1 in the address 999, since the content of A0 is first decremented 
and the 1 is written afterwards. 

These two methods of addressing are used to manage the Stack Pointer 
(SP). Since the stack is filled from top to bottom, the following is 
written to place a word (s.a. DO) on the stack: 

MOVE.B D0,-(SP) 

and to remove it from the stack, again in DO: 

MOVE.B (SP)+,D0 

This way the stack pointer always points to the byte last deposited on the 
stack. Here, again, you'll have to be careful that an access to the stack 
with a word or a long word is always on an even address. Thus, if you're 
going to deposit a byte on the stack, either use a whole word or make 
sure that the byte is not followed by a JSR or BSR. The JSR or BSR 
instructions deposit the addresses from which they stem on the stack in 
the form of a long word. 
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In the code above, the SP is generally replaced by the address register A7 
in the program code, since this register is always used as the SP. Thus, 
you can write A7 as well as SP, the resulting program is the same. How- 
ever, we recommend the use of SP, since this makes the code somewhat 
easier to read. After all, quite often you'll want to employ your own 
stacks, in which case the difference between the processor stack and your 
own stacks become very important 

These are the 12 ways of addressing the MC68000 processor. Here's a 
summary: 



No. 



Name 



Format 



1 data register direct Dn 

2 address register direct An 

3 address register indirect (An) 

4 address register indirect with post-increment (An)+ 

5 address register indirect with pre-decrement -(An) 

6 address register indirect with 16 bit displacement dl6(An) 

7 address register indirect with 8 bit index value 8(An,Rn) 

8 absolute short xxxx.W 

9 absolute long xxxxxxxx.L 

10 direct #'data' 

1 1 program counter indirect with 1 6 bit displacement dl 6(PC) 

12 program counter indirect with 8 bit index value d8(PC,Rn) 

The abbreviations used above have the following meanings: 

An address registers A0-A7 

Dn data registers D0-D7 

dl6 16 bit value 

d8 8 bit value 

Rn register D0-D7, A0-A7 

'data' up to a 32 bit value, (either .B .W or .L) 

These are the addressing modes used by the 68000 processor. The bigger 
brother of this processor, the 32 bit MC68020, has six more methods 
which we won't discuss here. 

Next, you're going to see under what conditions the processor can 
operate. 
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2.3 Operating modes 



In the previous section about registers you encountered the Status 
Register (SR). The individual bits of this register reflect the present 
operating condition of the processor. You differentiated between the 
system byte (bits 8-15) and the user byte (bits 0-7). Now, let's take a 
closer look at the system byte and its effects upon the operation of the 
processor. 



2.3.1 User and supervisor modes 

Isn't is rather strange that the processor classifies you either as a 'user' or 
a 'supervisor'? Both of these operating modes are possible, the user mode 
being the more common mode. In this mode it is impossible to issue 
some instructions, and that in your own computer! 

Don't worry, though, you can get around that, as well. The Amiga's 
operating system contains a function that allows us to switch the 
processor from one mode to the other. 

The mode is determined by bit 13 of the status register. Usually this bit 
is cleared (0), indicating that the processor is in user mode. It is possible 
to write directly into the status register, although this is a privileged 
instruction that can only be executed from the supervisor mode. Thus, 
this instruction could only be used to switch from the supervisor mode 
into the user mode, by using AND #$DFFF,SR to clear the supervisor 
bit. However, it is quite preferable to let the operating system perform the 
switch between these two modes. 

Now what differentiates these two modes in terms of their application? 

Well, we already mentioned the first difference: some instructions, such as 
MOVE xx, SR, are privileged and can only be executed from the supervisor 
mode. An attempt to do this in the user mode would result in an excep- 
tion and interruption of the program. Exceptions are the only way of 
switching to the supervisor mode, but more about that later. 

A further difference is in the stack range used. Although A7 is still used 
as the stack pointer, another memory range is used for the stack itself. 
Thus, the SP is changed each time you switch from one mode to the 
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other. Because of this you differentiate between the User SP (USP) and 
the Supervisor SP (SSP). 

Accessing memory can also depend on these two modes. During such 
accessing, the processor sends signals to the peripheral components in- 
forming them of the current processor mode. This way a 68Q00 computer 
can protect (privilege) certain memory ranges so they cannot be accessed 
by the user. 

In the supervisor mode it is possible to execute all instructions and access 
all areas of memory. Because of this, operating systems usually run in 
the supervisor mode. This is accomplished through the use of exceptions. 



2.3.2 Exceptions 



Exceptions are similar to interrupts on 6500 computers. This allows 
stopping a program, running a sub-program, and then restarting the 
stopped program. When an exception occurs the following steps are 
taken: 

1) The status register is saved 

2) The S bit in the SR is set (supervisor mode) and the T bit is 
cleared (no trace) 

3) The program counter and the user SP are saved 

4) The exception vector, which points to the needed exception 
routine, is retrieved 

5) The routine is executed 

The vectors mentioned, which contain the starting addresses for the var- 
ious routines, are located at the very beginning of the memory. Here's an 
overview of the vectors and their respective addresses: 
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Number 



Address 



Used for 





1 

2 

3 

4 

5 

6 

7 

8 

9 

10 

11 

15 

24 

25-31 

32-47 

64-255 



$000 RESET: starting SSP 

$004 RESET: starting PC 

$008 bus error 

$00C address error 

$010 illegal instruction 

$014 division by zero 

$018 CHK instruction 

$01C TRAPV instruction 

$020 privilege violation 

$024 trace 

$028 Axxx-instruction emulation 

$02C Fxxx-instruction emulation 

$030-$038 reserved 

$03C uninitialized interrupt 

$040-$05F reserved 

$060 unjustified interrupt 

$064-$083 level 1-7 interrupt 

$080-$0BF TRAP instructions 

$0C0-$0FF reserved 

$ 100-$3FF user interrupt vectors 



The individual entries in the table above need detailed explanation. So 
let's go through them one by one... 

RESET: starting SSP 

At reset, the long word stored at this location is used as the stack pointer 
for the supervisor mode (SSP). This way you can specify the stack for the 
RESET routine. 

RESET: starting PC 

Again at reset, the value at this location is used as the program counter. 
In other words, the RESET routine is started at the address stored here. 

Bus error This exception is activated by a co-processor when, for instance, a 

reserved or non-existent memory range is accessed. 

Address error This error occurs when a word or long word access is attempted at an odd 
address. 



Illegal instruction 



Since all MC68000 instructions consist of one word, a total of 65536 
different instructions are possible. However, since the processor doesn't 
know that many instructions, there are a number of words that are invalid 
instructions. Should such a word occur, this exception is prompted. 
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Division by zero 

Since the processor has a division function, and the division of anything 
by zero is mathematically undefined and thus illegal, this exception 
occurs when such an operation is attempted. 

CHK instruction 

This exception occurs only with the CHK instruction. This instruction 
tests that a data register's contents are within a certain limit. If this is not 
the case, the exception is activated. 

TRAPV instruction 

If the TRAPV instruction is executed and the V bit (bit 1) in the status 
word is set, this exception is prompted. 

Privilege violation 

If a privileged instruction is called from the user mode, this exception is 
activated. 

Trace If the trace bit (bit 15) in the status word is set, this exception is activated 

after each instruction that is executed. This method allows you to employ 
a step by step execution of machine programs. 

Axxx-ins true Hon emulation 

Fxxx-instruction emulation 

These two vectors can be used for a quite interesting trick. If an instruc- 
tion beginning with $A or $F (such as $A010 or $F200) is called, the 
routine to which the corresponding vector is pointing is accessed. In these 
routines you can create chains of other instructions, in effect expanding 
the processor's instruction vocabulary! 

Reserved These vectors are not used. 

Uninitialized interrupt 

This exception is activated when a peripheral component that was not 
initialized sends an interrupt. 

Unassigned interrupt 

Is activated when a BUS error occurs during the interrupt verification of 
the activating component. However, the interrupt is usually activated 
only by some type of disturbance. 

Level 1-7 interrupt 

These seven vectors point to the interrupt routines of the corresponding 
priority levels. If the level indicated in the status word is higher than the 
level of the occurring interrupt, the interrupt is simply ignored. 
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TRAP instructions 

These 16 vectors are used when a corresponding TRAP instruction occurs. 
Thus, TRAP instructions from TRAP #0 to TRAP #15 are possible. 

User interrupt vectors 

These vectors are used for interrupts which are activated by several peri- 
pheral components that generate their own vector number. 

At this point you don't want to delve any deeper into the secrets of excep- 
tions, since we'd be expanding this book beyond its framework. However, 
there's one last thing to say about exceptions: the exception routines are 
ended with the RTE (ReTurn from Exception) instruction, with which the 
original status is restored and the user program is continued. 



2.3.3 Interrupts 



Interrupts are processed similarly to exceptions. They are breaks (or inter- 
ruptions) in the program which are activated through hardware (such as a 
peripheral component or an external trigger). 

The interrupt level is stored in bits 8-10 of the status register. A value 
between and 7 indicates the interrupt level. There are eight different 
possible interrupts, each of which has a different priority. If the level of 
this interrupt happens to be higher than the value in the status register, 
the interrupt is executed, or otherwise ignored. 

When a valid interrupt occurs, the computer branches to the corresponding 
routine whose address is indicated in the exception vector table above. 

The interrupts are very important if you're trying to synchronize a 
program with connected hardware. In this manner, a trigger (s.a. the 
keyboard) which is to feed the computer data, can signal the request for a 
legal value using an interrupt The interrupt routine then simply takes the 
value directly. This method is also employed for the operation of the 
serial interface (RS232). 

We'll talk more about the use of interrupts at a later time. The last thing 
we want to mention about interrupts at this time is that, like exceptions, 
interrupt routines are terminated with the RTE instruction. 
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2.3.4 Condition codes 

When you write a program in any language, the need for a conditional 
operation arises quite often. For instance, in a BASIC program 

IF Dl = 2 THEND2 = 

represents a conditional operation. To write the equivalent in machine 
language, you first need to make the comparison: 

CMP #2,D1 

CMP stands for compare and compares two operands, in this case Dl and 
D2. How is this operation evaluated? 

For this purpose you have condition codes (CCs), which exist in the 
branch instructions of machine language. Because of this, you must 
specify when and where the program is to branch. 

The simplest variation of the branch instructions is an unconditional 
branch. The corresponding instruction is 'BRA address', although this 
won't help you here. After all, you need a conditional branch. 

To retain the result of an operation, in this case a comparison (CMP), 
several bits are reserved in the status word. Let's look at bit 2 first, which 
is the zero flag. This flag is set when the result of the previous operation 
was zero. 

To explain the relationship between CMP and the Z flag, you must first 
clarify the function of the CMP instruction. Actually this instruction per- 
forms the subtraction of the source operand from the destination operand. 
In the example above, the number 2 is subtracted from the content of the 
memory cell at Dl. Before the result of this subtraction is discarded, the 
corresponding flags are set. 

If the content of Dl in our example above happened to be 2, the result of 
the subtraction would be 0. Thus, the Z flag would be set, which can then 
be evaluated through a corresponding branch instruction. Our example 
would then look like this: 



30 



CMP 


#2,D1 


BNE 


UNEQUAL 


MOVE 


#0,D2 
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jcomparison, or subtraction 

Jbranch, if not equal (Z flag not set) 

Jotherwise execute D2 = 

;program branches to here 

BNE stands for Branch if Not Equal. This means, that if the Z flag was 
cleared (=0) by the previous CMP, the program branches to the address 
specified by BNE (here represented by UNEQUAL). The counterpart to 
the BNE instruction is the BEQ (Branch if EQual) instruction, which is 
executed if Z=l. 

Here's a list of all condition codes, which allow you to form conditional 
branches using the Bcc (cc=condition code) format: 

cc Condition Bits 



T 




true, corresponds to BRA 




F 




false, never branches 




HI 




higher than 


C *Z' 


LS 




lower or same 


C + Z 


CC, 


HS 


carry clear, higher or same 


C 


cs, 


LO 


carry set, lower 


C 


NE 




not equal 


Z' 


EQ 




equal 


Z 


VC 




Overflow clear 


V 


VS 




Overflow set 


V 


PL 




plus, positive 




MI 




minus, negative 




GE 




greater or equal 


N*V + N'*V , 


LT 




less than 


N*V'+N'*V 


GT 




greater than 


N*V*Z'+N'*V'*Z' 


LE 




less or equal 


Z + N*V + N'*V 



*=logic AND, +=logic OR, '=logic NOT 

Here are a few examples to demonstrate how these numerous conditions 
can be utilized: 

CMP #2,D1 

BLS SMALLER_EQUAL 

This branches if the content of Dl <= 2, whether Dl is 0, 1 or 2. In this 
example, the BLE instruction would allow the program to branch even if 
Dl is negative. You can tell this by the fact that the V bit is used in the 
evaluation of this expression (see chart above). When the sign is changed 
during the operation, this V bit is compared with the N bit. Should both 
bits be cleared (N bit=0 and V bit=0) after the CMP subtraction (Dl-2), 
the result has remained positive: the condition has not been met. 
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The conditions EQ and NE are quite important for other uses, as well. For 
instance, they can be used to determine if particular bits in a data word are 
set, by writing the following sequence... 



AND #%00001111,D1 ;masks bits out 

BEQ SMALLER ;branches when none of the four 

; ;lower bits is set 
CMP #%00001111,D1 

BEQ ALL jbranches when all four bits set 

The AND instruction causes all bits of Dl to be compared with the bits 
of the parameter (in this case #%00001111). If the same bits are set in 
both bytes, the corresponding bits are also set in the result If one bit of a 
pair is cleared, the resulting bit is zero as well. Thus, in the result, the 
only bits that are set are those bits of the lowest four that were set in Dl. 

This technique is known as masking. In the example above, only the 
lowest four bits were masked out, which means that in the resulting byte, 
only the lowest four appear in their original condition. All other bits are 
cleared with the AND operand. Of course you can use any bit combina- 
tion with this method. 

If no bit at all is set in the result, the zero flag is set, thus fulfilling the 
BEQ condition and branching the program. Otherwise, the next instruc- 
tion is processed, in which Dl is compared with %00001111. When both 
are equal, at least all of the four lowest bits of the original byte have been 
set, in which case the following BEQ instruction branches. 

Aside from CMP, the CC and CS conditions can also be used to deter- 
mine whether a HI bit was pushed out of the data word during data 
rotation with the ROL and ROR instructions. 

Before you move on the instruction vocabulary of the MC68000, we'd 
like to give you another tip: 

The AssemPro assembler makes it quite easy to try every command in all 
possible situations. Take the CMP command which we've been talking 
about, for example. To test this command with various values and to 
receive the results of the comparisons directly via the flags, try the 
following. 

Type the following into the editor. 

run: 

cmp $10,dl 
bra run 
end 



32 



Abacus 2. The MC68000 Processor 



Assemble it, save the resulting code and enter the debugger. After re- 
loading the code you can then single step through the program observing 
the results the program has on the flags. Try changing the values in 
register Dl and see how higher and lower values affect the flags. 

By the way, using the start command as this time causes it,to run forever. 
Well, at least until reset is hit, which isn't exactly desirable, either.... 

This procedure isn't limited to just the CMP instruction. You can use it 
to try any other instruction you're interested in. 
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2.4 The 68000 Instructions 



It's about time to explain the MC68000 instructions. You don't have 
room for an in-depth discussion of each instruction in this book; for that 
purpose we recommend Programming the 68000 from Sybex by Steve 
Williams. 

The following tables show the required parameters and arguments for each 
instruction. AssemPro owners have access to built in help tables covering 
effective addressing modes and many of the Amiga Intuition calls. The 
following notation is used for arguments: 



Label 


a label or address 


Reg 


register 


An 


address register n 


Dn 


data register n 


Source 


source operand 


Dest 


destination operand 


<ea> 


address or register 


#n 


direct value 



Here is a short list of the instructions for the MC68000 processor, 
AssemPro owners can simply place the cursor at the beginning of the 
instruction and press the help key to see the addressing modes allowed: 



Bcc 


Label 


BRA 


Label 


BSR 


Label 


CHK 


<ea>,Dx 


DBcc 


Reg,Label 


JMP 


Label 


JSR 


Label 


NOP 




RESET 




RTE 




RTR 




RTS 




Sec 


<ea> 


STOP 




TRAP # 


n 


TRAPV 





Meaning 

conditional branch, depends on condition 

unconditional branch (similar to JMP) 

branch to subprogram. Return address is deposited 

on stack, RTS causes return to that address. 

check data register for limits, activate the CHK 

instruction exception 

check condition, decrement and branch. 

jump to address (similar to BRA) 

jump to a subroutine. Return address is deposited 

on stack, RTS causes return to that address. 

no operation 

reset peripherals (Caution!) 

return from exception 

return with loading of flags 

return from subroutine (after BSR or JSR) 

set a byte to -1 when condition is met 

stop processing (Caution!) 

jump to an exception 

check overflow flag, then TRAPV exception 
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Here are a few important notes... 

When a program jumps (JSR) or branches (BSR) to a subroutine, the 
return address to which the program is to return is placed on the stack. At 
the RTS instruction, the address is pulled back off the stack, and the 
program jumps to that point. 

Let's experiment a little with this procedure. Please enter the following 
short program: 

run: 

pea subprogram ; address on the stack 

jsr subprogram ; subprogram call 

move.l (sp) +,dl ; get long word from stack 

; illegal ; for assemblers without 

/debuggers 

subprogram: 

move.l (sp),dO ; return address in DO 

rts ; and return 

end 

The first instruction, PEA, places the address of the subprogram on the 
stack. Next, the JSR instruction jumps to the subprogram. The return 
address, or the address at which the main program is to continue after the 
completion of the subprogram, is also deposited on the stack at this 
point. 

In the subprogram, the long word pointed to by the stack pointer is now 
loaded into the data register DO. After that, the RTS instruction pulls the 
return address from the stack, and the program jumps to that address. 

Back in the main program, the long word which is on the top of the 
stack, is pulled from the stack and written into Dl. Assemblers that do 
not have the debugging features of AssemPro may need the ILLEGAL 
instruction so they can break the program and allow you to view the 
register contents. 

Assemble the program and load the resulting code into the debugger. 
Single step thru the program and examine the register contents. 

Here you can see that DO contains the address at which the program is to 
continue after the RTS command. Also, Dl contains the address of the 
subprogram which you can verify by comparing the debugger listing. 

The STOP and RESET instructions are so powerful that they can only be 
used in the supervisor mode. Even if you do switch to the supervisor 
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mode, you should not use these instructions if there is any data in mem- 
ory that has not been saved and you wish to retain. 

The TRAP instruction receives a number between and $F, which deter- 
mines the particular TRAP vector (addresses $0080-$00BF) and thus the 
corresponding exception routine. Several operating systems for the 68000 
utilize this instruction to call operating system functions. You'll deal 
more with this instruction later. 

In the short sample program that compared two numbers, the CMP 
instruction performed an arithmetic function, namely a subtraction. This 
subtraction could be performed with an actual result as well using the 
SUB instruction. The counterpart to this is in addition, for which the 
ADD instruction is used. In eight bit processors, like the 6502, these two 
arithmetic functions are the only mathematical operations. The 
MC68000, can also multiply, divide, and perform these operations with a 
variety of data sizes. 

Most of the functions require two parameters. For instance the ADD 
instruction... 

ADD source, destination 

where source and destination can be registers or memory addresses. Source 
can also be a direct value (#n). The result of the operation is placed in the 
destination register or the destination address. This is the same for all 
operations of this type. These instructions can be tried out with the 
Assempro assembler. In this case we recommend the use of a register as 
the destination. 

Here's an overview of the arithmetic operations with whole numbers: 



Mnemoni 


C 


ADD 


source,dest 


ADDA 


source,An 


ADD I 


#n,<ea> 


ADDQ 


#n,<ea> 


ADDX 


source,dest 


CLR 


<ea> 


CMP 


source,dest 


CMPA 


<ea>,An 


CMP I 


#n,<ea> 


CMPM 


source,dest 



Meaning 

binary addition 

binary addition to an address register 

addition with a constant 

fast addition of a constant which can 

be only from 1 to 8 

addition with transfer in X flag 

clear an operand 

comparison of two operands 

comparison with an address register 

comparison with a constant 

comparison of two memory operands 
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Mnemonic 



Meaning 



DIVS 



source,dest 



DIVU 


source,dest 


EXT 


Dn 


MULS 


source,dest 


MULU 


source,dest 


NEG 


<ea> 


NEGX 


<ea> 


SUB 


source,dest 


SUBA 


<ea>,An 


SUB I 


#n,<ea> 


SUBQ 


#n,<ea> 


SUBX 


source,dest 


TST 


<ea> 



sign-true division of a 32 bit 

destination by a 16 bit source 

operand. The result of the division is 

stored in the LO word of the 

destination, the remainder in the HI 

word. 

division without regard to sign, 

similar to DIVS 

sign-true expansion to twice original 

size (width) data unit 

sign-true multiplication of two words 

into one long word 

multiplication without regard to sign, 

similar to MULS 

negation of an operand (twos 

complement) 

negation of an operand with transfer 

binary subtraction 

binary subtraction from an address 

register 

subtraction of a constant 

fast subtraction of a 3 bit constant 

subtraction with transfer in X-Flag 

test an operand and set N and Z flag 



For the processing of whole numbers, the processor can operate with 
BCD numbers. These are Binary Coded Decimal numbers, which means 
that the processor is working with decimals. In this method, each halfbyte 
contains only numbers from to 9, so that these numbers can be easily 
processed. For this method, the following instructions are available: 



Mnemonic 




Meaning 


ABCD 


source,dest 


addition of two BCD numbers 


NBCD 


source,dest 


negation of a BCD number (nine 
complement) 


SBCD 


source,dest 


subtraction of two BCD numbers 



Again, we recommend that you try this out yourself. Although handling 
the BCD numbers is relatively easy, it can be rather awkward at first. Be 
sure that you enter only BCD numbers for source and destination, since 
the results are not correct otherwise. 

Next are the logical operations, which you might know from BASIC. 
With these functions, you can operate on binary numbers bit for bit. 
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Mnemonic 




Meaning 


AND 


source,dest 


logic AND 


AND I 


#n,<ea> 


logic AND with a constant 


EOR 


source,dest 


exclusive OR 


EORI 


#n,<ea> 


exclusive OR with a constant 


NOT 


<ea> 


inversion of an operand 


OR 


source,dest 


logic OR 


ORI 


#n,<ea> 


logic OR with a constant 


TAS 


<ea> 


check a byte and set bit 7 



Single bits can also be manipulated by the following set of instructions: 



Mnemonic 




Meaning 


BCHG 


#n,<ea> 


change bit n (0 is changed to 1 and 
vice versa) 


BCLR 


#n,<ea> 


clear bit n 


BSET 


#n,<ea> 


set bit n 


BTST 


#n,<ea> 


test bit n, result is displayed in Z flag 



These instructions are particularly important from the manipulation and 
evaluation of data from peripherals. After all, in this type of data, single 
bits are often very significant. You'll come across this more in later 
chapters. 

The processor can also shift and rotate an operand within itself ('n' 
indicates a register, '#' indicates a direct value which specifies the number 
of shiftings)... 



Mnemonic 




Meaning 


AS 


n,<ea> 


arithmetic shift to the left (*2 A n) 


ASR 


n,<ea> 


arithmetic shift to the right (/2 A n) 


LSL 


n,<ea> 


logic shift to the left 


LSR 


n,<ea> 


logic shift to the right 


ROL 


n,<ea> 


rotation left 


ROR 


n,<ea> 


rotation right 


ROXL 


n,<ea> 


rotation left with transfer in X flag 


ROXR 


n,<ea> 


rotation right with transfer in X flag 



All these instructions allow you to shift a byte, a word or a long word to 
the left or right. It's not too surprising that this is the equivalent of mul- 
tiplying (dividing) the number by a power of 2. Here's a little example to 
demonstrate why. 

Let's take a byte containing the value 16 as an example. In binary, it 
looks like this: 
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%00010000 = 16 

Now, if you shift the byte to the left by inserting a at the right, you'll 
get the following result... 

%00010000 shifted to the left equals 
%00100000 = 32, in effect 16*2 

Repeated shifting results in repeated doubling of the number. Thus, if you 
shift the number n times, the number is multiplied by 2V 

The same goes for shifting to the right. However, this operation has a 
slight quirk: here's a sample byte with the value 5: 

%00000101 = 5, shifted once to the right equals 
%00000010 = 2 

The answer in this case is not 2.5 as you might expect. The result of 
such a division is always a whole number, since any decimal places are 
discarded. If you use the DIV instruction instead of shifting, you'll retain 
the digits to the right of the decimal point. However, shifting is some- 
what faster, and shifting can also receive long words as results. 

After explaining the principle of shifting, you still need to know why 
more than two instructions are required for the procedure. Well, this is 
because there are several different types of shifting. 

First, you must differentiate between shifting and rotating. In shifting, 
the bit that is added to the left or the right side is always a zero. In 
rotating, it is always a specific value that is inserted. This means that 
with the ROR or the ROL instruction, the bit that is taken out on one 
side is the one that is inserted on the other. With the ROXR and the 
ROXL instructions this bit takes a slight detour to the X flag. Thus, the 
content of the flag is inserted into the new bit, while the old bit is loaded 
into the flag. 

Shifting, as well, I.as two variations: arithmetic and logical shifting. 
You've already dealt with logical shifting. In this variation, the inserted 
bit is always a zero, and the extracted bit is deposited in the C flag and in 
the X flag. 

Although the highest bit, which always represents the sign, is shifted in 
arithmetic shifting, the sign is still retained by ASR. This has the advan- 
tage that when these instructions are used for division, the operation 
retains the correct sign (-10/2 equals -5). However, should an overflow or 
underflow cause the sign to change, this change is noted in the V flag, 
which always indicates a change in sign. With logical shifting this flag is 
always cleared. 
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Now to the instructions that allow you to move data. These are actually 
the most important instructions for any processor, for how else could you 
process data? 



Mnemonic 




Meaning 


EXG 


Rn,Rn 


exchange of two register contents 
(don't confuse with SWAP!) 


LEA 


<ea>,An 


load an effective address in address 
register An 


LINK 


An,#n 


build stack range 


MOVE 


source,dest 


carry value over from source to 
destination 


MOVE 


SR,<ea> 


transfer the status register contents 


MOVE 


<ea>,SR 


transfer the status register contents 


MOVE 


<ea>,CCR 


load flags 


MOVE 


USP,<ea> 


transfer the user stack pointer 


MOVE 


<ea>,USP 


transfer the user stack pointer 


MOVEA 


<ea>,An 


transfer a value to the address register 

An 

transfer several registers at once 


MOVEM 


Regs,<ea> 


MOVEM 


<ea>,Regs 


transfer several registers at once 


MOVEP 


source,dest 


transfer data to peripherals 


MOVEQ 


#n,Dn 


quickly transfer an 8 bit constant to 
the data register Dn 


PEA 


<ea> 


deposit an address on the stack 


SWAP 


Dn 


swap the halves of the register (the 
upper 16 bits with the lower) 


UNLK 


An 


unlink the stack 



The LEA or PEA instructions are often used to deposit addresses in an 
address register or on the stack. The instruction 

LEA label,A0 

loads the address of the label 'label' into the address register AO. In prac- 
tice, this corresponds to 

MOVE.L #label,A0 

which is equivalent to 

PEA label 

All these instructions deposit the address of 'label' on the stack. The fol- 
lowing instruction also does this: 

MOVE.L #label,- (SP) 
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The LEA instruction becomes much more interesting when the label is 
replaced by indirect addressing. Here's an example: 

LEA 1 (A0,D0),A1 

The address that's produced by the addition of 1 (direct value-offset) 
+A0+D0 is located in Al. To duplicate this instruction with MOVE 
would be quite cumbersome. Take a look: 

MOVE.L A0,A1 
ADD.L D0.A1 
ADDQ.L #1,A1 

As you can see, the LEA instruction offers you quite some interesting 
possibilities. 

Those are all the instructions of the MC68000. Through their combina- 
tion using the diverse methods of addressing, you can create a great 
number of different instructions, in order to make a program as efficient 
as possible. 

The following table is an overview of all MC68000 instructions along 
with their possible addressing types and the influence of flags. The fol- 
lowing abbreviations are used: 

x=legal s=source only d=destination only 

-=not affected 0=cleared *=modified accordingly 

l=set u=undetermined P=privileged 
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Mnemonic 


1 


2 


3 


4 


5 


6 


7 


8 


9 


10 


11 


12 


XNZVC P 


ABCD 




X 








X 


















ADD 




s 


s 


X 


X 


X 


X 


X 


X 


X 


s 


s 


s 


• •••* 


ADDA 




X 


X 


X 


X 


X 


X 


X 


X 


X 


X 


X 


X 




ADD I 




X 




X 


X 


X 


X 


X 


X 


X 








• •*•• 


ADDQ 




X 


X 


X 


X 


X 


X 


X 


X 


X 








• ••*• 


ADDX 




X 








X 
















• •••• 


AND 




s 




X 


X 


X 


X 


X 


X 


X 


s 


s 


s 


-**oo 


AND I 




X 




X 


X 


X 


X 


X 


X 


X 








-**oo 


ASL, 


ASR 


X 




X 


X 


X 


X 


X 


X 


X 








• • **• 


Bcc 






























BCHG 




X 




X 


X 


X 


X 


X 


X 


X 








— • — 


BCLR 




X 




X 


X 


X 


X 


X 


X 


X 








— • — 


BRA 






























BSET 




X 




X 


X 


X 


X 


X 


X 


X 








— * — 


BSR 






























BTST 




X 




X 


X 


X 


X 


X 


X 


X 


z 


X 


X 


— • — 


CHK 




X 




X 


X 


X 


X 


X 


X 


X 


X 


X 


X 


-*uuu 


CLR 




X 




X 


X 


X 


X 


X 


X 


X 








-0100 


CMP 




X 


X 


X 


X 


X 


X 


X 


X 


X 


X 


X 


X 


_• •*• 


CMP A 




X 


X 


X 


X 


X 


X 


X 


X 


X 


X 


X 


X 


_•*•• 


CMP I 




X 




X 


X 


X 


X 


X 


X 


X 








_•••• 


CMPM 








X 






X 


X 


X 


X 




X 


X 


_••• 


cpGEN 




























DBcc 






























DIVS 




X 




X 


X 


X 


X 


X 


X 


X 


X 


X 


X 


_• **o 


DIVU 




X 




X 


X 


X 


X 


X 


X 


X 


X 


X 


X 


-•••0 


EOR 




X 




X 


X 


X 


X 


X 


X 


X 








-**oo 


EORI 




X 




X 


X 


X 


X 


X 


X 


X 








-**oo 


EORI 


CCR 


























• *••• 


EORI 


SR 


























• •* •• 


EXG 






























EXT 




























-**oo 


EXTB 




























-**oo 


ILLEGAL 




























JMP 








X 






X 


X 


X 


X 




X 


X 




JSR 








X 






X 


X 


X 


X 




X 


X 




LEA 








X 






X 


X 


X 


X 




X 


X 




LINK 






X 
























LSL, 


LSR 






X 


X 


X 


X 


X 


X 


X 








• **o* 


MOVE 




X 


s 


X 


X 


X 


X 


X 


X 


X 


s 


s 


s 


-**oo 


MOVEA 


X 


X 


X 


X 


X 


X 


X 


X 


X 


X 


X 


X 




MOVE 


to CCR 


X 




X 


X 


X 


X 


X 


X 


X 


X 


X 


X 


* •• •• 


MOVE 


from SR 


X 




X 


X 


X 


X 


X 


X 


X 








p 


MOVE 


to SR 


X 




X 


X 


X 


X 


X 


X 


X 


X 


X 


X 


•*••* p 
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Mnemonic 


1 


2 


3 


4 


5 


6 


7 


8 


9 


10 


11 


12 


XNZVC 


P 


MOVE USP 




X 
























p 


MOVEM 








X 


s 


d 


X 


X 


X 


X 




s 


s 






MOVEP 




s 


d 


























MOVEQ 




d 
























-**00 




MULS 




X 




X 


X 


X 


X 


X 


X 


X 


X 


X 


X 


-**00 




MULU 




X 




X 


X 


X 


X 


X 


X 


X 


X 


X 


X 


-**00 




NBCD 




X 




X 


X 


X 


X 


X 


X 


X 








*u*u* 




NEG 




X 




X 


X 


X 


X 


X 


X 


X 








***** 




NEGX 




X 




X 


X 


X 


X 


X 


X 


X 








***** 




NOP 
































NOT 




X 




X 


X 


X 


X 


X 


X 


X 








_**oo 




OR 




s 




X 


X 


X 


X 


X 


X 


X 


s 


s 


s 


_**oo 




OR I 




X 




X 


X 


X 


X 


X 


X 


X 








_**oo 




PEA 








X 






X 


X 


X 


X 




X 


X 






RESET 






























p 


ROL, ROR 






X 


X 


X 


X 


X 


X 


X 








_**o* 




ROXL, 


ROXR 






X 


X 


X 


X 


X 


X 


X 








_* *o* 




RTE 






























p 


RTR 




























* * * ** 




RTS 
































SBCD 




X 








X 
















*u*u* 




Sec 




X 




X 


X 


X 


X 


X 


X 


X 












STOP 






















X 










SUB 




s 


s 


X 


X 


X 


X 


X 


X 


X 


s 


s 


s 


***** 




SUBA 




X 


X 


X 


X 


X 


X 


X 


X 


X 


X 


X 


X 






SUBI 




X 




X 


X 


X 


X 


X 


X 


X 








***** 




SUBQ 




X 


X 


X 


X 


X 


X 


X 


X 


X 








* * * • * 




SUBX 




X 








X 
















* * * ** 




SWAP 




X 
























_**oo 




TAS 




X 




X 


X 


X 


X 


X 


X 


X 








_**oo 




TRAP 






















X 











TRAPV 
































TST 




X 




X 


X 


X 


X 


X 


X 


X 








_**oo 




UNLK 






X 
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The instructions that you've learned so far are incomprehensible to the 
MC68000 processor. The letters MOVE mean absolutely nothing to the 
processor — it needs the instructions in binary form. Every instruction 
must be coded in a word — which normally takes a lot of work. 

An assembler does this work for you. An assembler is a program that 
translates the instructions from text into the corresponding binary instruc- 
tions. The text that is translated is called mnenomic or memcode. It's a 
lot easier working with text instructions — or does $4280 mean more to 
you than CLR.L DO? 

This chapter is about working with assemblers. We'll describe the fol- 
lowing three: 

ASSEM This is the assembler from the Amiga's development package. This 

assembler is quite powerful, but it is clearly inferior to it's two fellow 
compilers in some areas. 

AssemPro This is the Abacus assembler. It has a debugger in addition to the assem- 

bler. This lets you test and correct programs. In our opinion, it is the best 
one to use for writing and testing practice programs. For this reason, we 
wrote the programs in this book with this assembler. 

KUMA-SEKA This is a popular assembler that also has a debugger. 

All assemblers perform a similar task — they translate memcode, so that 
you can write a runnable program to disk. To test the program directly, 
you need a debugger which is something ASSEM doesn't have. 
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3.1 The Development Assembler 



This assembler is a plain disk assembler. That means that it can only 
assemble text files that are on disk and write the results back to disk. You 
can't make direct input or test run the new program. 

You can call ASSEM from the CLI by typing ASSEM followed by 
parameters that specify what you wish the assemble to do. 

In the simplest case, you call it like this: 

ASSEM Source -0 Destination 

Source is the filename of the file containing the program text. Destina- 
tion is the name of the file that contains the results of assembling after 
the process is over. The "-0" means that the following name is used for 
the object file. 

There are several other parameters that can be passed. These are written 
with their option (ie. -O), so that the assembler knows what to do with 
the file that you've told it to use. The following possible options must 
be followed by a filename: 

-O Object file 

-V Error messages that occur during assembling are written to a file. 

If this isn't given, the error messages appear in the CLI 

window. 
-L The output of the assembled program lines are sent to this file. 

You can also use "PRT:" to have it printed. 
-H This file is read in at the beginning of the assembled file and 

assembled along with it. 
-E A file is created that contains lines which have EQU instruc- 

tions. 
-C This option isn't followed by a filename but by another option. 

You can also use OPT to do this. The following options are 

available: 

OPT S A symbol table is created which contains all the labels 
and their values. 

OPT X A cross-reference list is created (where labels are used) 

OPT W A number must follow this option. It sets the amount 
of work space to be reserved. 
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The assembler creates an object file. This is not runnable. To make it 
runnable, you need to call the linker, ALINK. This program can link 
several assembled or compiled object files together to make a runnable 
program. In the simplest case, you enter the following instruction in the 

cli: 

ALINK Source TO Destination 

Source is the object file produced by the assembler. Destination is the 
name of the program. It can be started directly. 
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3.2 AssemPro 



Abacus's AssemPro is a package which combines editor, assembler and 
debugger in an easy to use package. 

The AssemPro program is divided into several windows — one for the 
assembler, the editor, the debugger and several help functions. Producing 
a program is very easy: 

1) Write the program with the editor and then store it to disk. 

2) Start the assembler, so that the program is translated. 

3) If desired, start the debugger, load the program and test it. 

Within the debugger you can work through parts of the program or even 
through single commands. As after each one of these steps the debugger 
shows you the state of registers and flags in its status register, you can 
easily try the programs presented in this book. 

You need to load Assempro only once when working with machine 
language programs. Thus you don't need to save back and to between 
editor, assembler, linker and debugger. 

Assempro has an especially interesting function: the reassembler. With 
this debugger function you are able to convert runable programs into the 
source text of the program. Once you have made the source text, you can 
edit the program using the editor and assemble it again. Assempro is 
equipped with functions other assemblers miss. There are however, some 
differences you should know about As many programs you see were writ- 
ten for the K-SEKA, be aware of one difference: the EVEN command. 
AssemPro uses the ALIGN instruction. 

Note, that when entering and assembling one of the programs in Assem- 
pro you must make sure that you place an END directive at the end of the 
source text 

The following is an introduction into working with Assempro and the 
programs in this book. 

Start AssemPro normally, next click on the editor window and start 
typing in your program. If the program is on disk already, load it by 
selecting the appropriate menu or by using the key combination right 
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<AMIGA> key and <o>. To do this you only need to click on the file- 
name in the displayed requestor and click the OK gadget. 

Once you have typed in or loaded the program into the editor, you can 
assemble it. It is best to save your source before you start assembling. 
You assemble your program by clicking on the assembler window 
displayed above the editor window and pressing <AMIGA> and <a>. You 
can then chose how to locate your program in the memory. Remember 
that data used by the co-processors must be located in CHIP RAM. 

By clicking OK you start the assembler process. If you additionally select 
"breakable", you can cancel the process by pressing both shift keys. If 
any error occurs during assembling, Assempro uses a window to tell you 
this. Use this window to correct the error and continue with "Save and try 
again". 

Now the runable program is located in the Amiga's memory. Use the 
menu item "Save as" to save it on disk. If you want to store it on RAM 
disk, click the given filename and enter RAM: in front of this name. In 
addition you can click on the menu item "ICON" and chose if you only 
want the program itself on disk but the icon too. Use this icon to start 
the program at a later time from the Workbench. 

To test-run the program, you move the debugger window to the fore- 
ground of the screen (for instance by clicking on the back gadget). Use 
"Load" in the debugger menu or <AMIGA> <o> to call the select-file 
window, where you select the saved program. The program is then loaded 
into the memory and its shown disassembled. 

The highlighted line (orange) represents the current state of the program 
counter. This is the line where the processor reads its next instruction, 
provided you tell the processor so. There are three ways to do so. 

The first one is to start the program with "Start". This alternative does 
not enable you to stop the program if anything goes wrong. 

The second possibility, "Start breakable" is better in this respect. After 
the program starts, it continuously displays the register's contents on the 
left side of the window. In addition to that you can cancel the process by 
pressing <Esc>. Note that this only works if your program doesn't use 
the <Esc> key itself. 

The third possibility enables you to only partly run your program. You 
can do this by stepping through the program or by placing breakpoints 
throughout the program. You place these by clicking on the desired 
address and then pressing <AMIGA> <b>. "BREAKPOINT" is displayed 
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where the command was displayed before. If you start the program now, it 
stops whenever it comes across one of the breakpoints. 

You can start a small part of the program by moving the mouse pointer 
to the orange line, clicking the left button and holding it down while you 
drag the mouse pointer downward. If you release the button, the processor 
works through this part of the program, stopping at the line, where you 
positioned the mouse pointer. This is a very useful method to step by 
step test a program. 

AssemPro has another helpful window: the Table. This window lists the 
valid address methods for instructions and the parameters of Amiga func- 
tions. This is extremely helpful whenever you are not sure about one of 
the instructions. 
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3.3 The K-SEKA Assembler 



The SEKA assembler, from KUMA, has a simple text editor and a 
debugger in addition to the assembler. This program is controlled by 
simple instructions and is easy to use. It is also multi-functional and 
quick, so it is great for small test and example programs. You can use it 
to write bigger programs once you've gotten use to the editor. Now let's 
look at the editor. 

To load a program as source code (text) into the editor, enter "r" (read). 
The program asks you for the name of the file with the "FILENAME>" 
prompt. You then enter the name of the text file. If you created the file 
with SEKA, the file is stored on disk with ".S" on the end of its name. 
You don't need to include the ".S" when you load the file. That's taken 
care of automatically. ("S" stands for source.) 

You can store the programs you've just written or modified by using the 
"w" instruction. The program asks you for the name. If you enter "Test", 
the file is written to disk with "TestS" as its name. This is a normal text 
file in ASCII format. 

There are two ways to enter or change programs: using the line editor or 
using the screen editor. You can enter the second by hitting the <Esc> 
key. The upper screen section is then reserved for the editor. You can 
move with the cursor keys and change the text easily. The lines that you 
enter are inserted into the existing text and automatically numbered. By 
hitting the <Esc> key again, you leave the screen editor. 

There's really not much to say about this editor. It's really just for simple 
insertions and changes. Other functions are called in normal instruction 
mode, the mode in which ">" is the input prompt. 

The following instructions are available to you for text editing (<n> 
stands for a number. The meaning of the instructions is in parenthesis.) 
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Instruction 



Function 



t (Target) 
t <n> 
b (Bottom) 
u(Up) 
u <n> 
d(Down) 
d<n> 
z(Zap) 
z <n> 
e(Edit) 
e <n> 
ftext (Find) 



i (Insert) 



ks (Kill Source) 



o (Old) 
p (Print) 
p <n> 



Puts the cursor on the highest line in the text. 
Puts the cursor on line n. 
Puts the cursor on the last line of the text. 
Go up one line. 
Go up n lines. 
Go down one line. 
Go down n lines. 
Deletes the current line. 
Deletes n lines starting at the cursor line. 
Let's you edit the current line (and only that line). 
Edit from line n. 

Searches for the text entered starting at the current line. 
The case of a letter makes a difference, so make sure to 
enter it correctly. Blanks that appear after the f are 
looked for as well! 

Continues searching beyond the text that was previous- 
ly given. 

Starts the line editor. Now you can enter a program line 
by line. However, you can't use the cursor to move 
into another line. Line numbers are generated automati- 
cally. The lines that follow are moved down, not erased. 
The source text is deleted if you answer "y" when the 
program asks if you're sure. Otherwise nothing 
happens. 

Cancels the "ks" function and saves the old text. 
Prints the current line. 
Prints n lines starting at the cursor line. 



Those are K-SEKA's editor functions. In combination with the screen 
editor, they allow for simple text editting. You can, for example, delete 
the current line (and other lines) while working in the screen editor by 
hitting <Esc> to get into instruction mode and then entering "z" (or "z 
<n>"). 

If you'd like to edit all the lines that contain "trap", for example, you can 
do the following: 

- Jump to the beginning of the text using "t". 

- Search for a "trap" instruction by entering "ftrap" in the first line. 

- Press <Esc> and edit the line. 

- Press <Esc> again to get into instruction mode. 

- Search using "f ', <Esc>, etc. until you get to the end of the text. 

This sounds very clumsy, but in practice it works quite well and goes 
quickly. Experiment with the editor a bit, so that you can get use to it. 
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Now here are the instructions for working with disks: 



Instruction 



Function 



v (View Files) 

kf (Kill File) 
r(Read) 

ri (Read Image) 

rx (Read from Auxiliary) 
rl (Read Link file) 

w (Write) 

wi (Write Image) 

wx (Write to Auxiliary) 

wl (Write Link file) 



Look at the disk's directory. You can also 
include the disk drive or subdirectory that 
interests you. For example, "vc" causes the "c" 
subdirectory to be listed and makes it the 
current directory. 

The program asks for the name of a file. The 
file is deleted (and you aren't asked if you are 
sure either — so be careful). 
After inputting this instruction, you'll be 
asked which file to load (FILENAME>). The 
file that you specify is then loaded. If only "r" 
is entered, a text file is loaded in the editor. 
Loads a file into memory. After you've entered 
the filename, SEKA asks for the address the 
file should begin at in memory (BEGIN>) and 
the highest address that should be used for the 
file (END>). 

This works just like the "ri" function except 
that it reads from the serial port instead of 
from the disk. (You don't need a filename). 
This instruction reads in a SEKA created link 
file. First you'll be asked if you're sure, be- 
cause the text buffer is erased when the link 
file is loaded 

After entering this instruction, you'll be asked 
for the name of the file the text should be 
written to. A ".S" is automatically appended to 
the name, so that it can be recognized as a 
SEKA file. 

Stores a block of memory to disk after the 
name, beginning and end are entered. 
This is similar to "wi"; the only difference is 
that the output is to the serial intrface. 
Asks for the name and then stores a link file 
that was assembled with the "I" option to disk. 
If this isn't available, the message "** Link 
option not specified" appears. 



Once you've typed in or loaded a program, you can call the assembler and 
have the program translated. Just enter "a" to do so. You'll then be asked 
which options you want to use. If you enter a <Return>, the program is 
assembled normally — ie the results of translating a program in memory is 
stored in memory. Then the program can be executed right a way. 
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You can enter one or more of the following options however: 

v The output of the results goes to the screen 

p or 

e goes to the printer with a title line. 

h The output stops after every page and waits for a key stroke. 

This is useful for controlling output to the screen or for putting 

new sheets of paper in the printer. 

This option allows the assembler to optimize all possible branch 
instructions. When possible, a .S is appended to the branch 
instructions. This allows the program code to be shorter than it 
would otherwise be. Several messages appear, but you can ig- 
nore them. 

1 This option caused linkable code to be produced. You can save it 
with the "wl" instruction and read it with the "rl" instruction. 

A symbol table is included at the end of the listing if desired. The table 
contains all labels and their values. It also contains macro names. A mac- 
ro allows several instructions to be combined into a single instruction. 

For example, suppose you wrote a routine that outputs the text that 
register AO points to. Every time you need to use the routine, you must 
type: 

lea text,aO jPointer to text in AO 
bsr pline JOutput text 

You can simplify this by defining a macro for this function. To do this, 
put the following at the beginning of the program: 

print: macro JMacro with the name "print" 

lea ?l,aO jParameter in AO 

bsr pmsg JOutput text 

endm ;end of macro 

Now, you can simply write the following in your program: 

print text JOutput text 

This line is replaced using the macro during assembly. The parameter 
"text" is inserted where "?1" appears in the macro. You can have several 
parameters in a macro. You give them names like "?2", "?3", etc... 

You can also decide whether you'd like to see the macros in the output 
listing of the assembler. This is one of the pseudo-operators (Pseudo-ops) 
that are available in the assembler. The SEKA assembler has the fol- 
lowing pseudo-ops: 
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db Defines one or more data items that should appear in this loca- 

tion in the program. The word length can be specified with .B, 

.W, or .L — and if this is left off, .B is used. Text can be entered 

in quotation marks or apostrophes. 

For example: dc.b "Hello",10,13,0 
blk Reserves a number of bytes, words or long words, depending on 

whether .B, .W or .L is chosen. The first parameter specifies the 

number of words to be reserved. The second (which is optional) 

is used to fill the memory area. 

For example: blk.w 10,0 

The parameter that follows the org instruction is the address 

from which the (absolute) program should be assembled. 

For example: org $40000 

Causes the program to be assembled in relative mode, the mode 

in which a program is assembled starting at address 0. The 

Amiga takes care of the new addressing after the program is 

loaded 

This means that from here on only data appear. This can be left 

out. 

Makes the current address even by sometimes inserting a fill 

byte. 

The opposite of "even" — it makes the address odd. 

Assembling ends here. 

Used for establishing the value of a label. 

For example: Value = 123 or Value: equ 123 

Turns the output on again (aften nlist). You can use the fol- 
lowing parameters to influence the output: 

c Macro calls 

d Macro definitions 

e Macro expansion of the program 

x Code expansions 

For example: list e 
nlist Turns off output. You can use the same parameters here as with 

"list", 
page Causes the printer to executed a page feed, so that you'll start a 

new page, 
if The following parameter decides whether you should continue 

assembling. If it is zero, you won't continue assembling, 
else If the "if' parameter is zero, you'll begin assembling here, 
endif End of conditional assembling 
macro Start of a macro definition 
endm End of a macro definition 
?n The text in the macro that is replaced by the nth parameter in the 

calling line. 
?0 Generates a new three digit number for each macro call — this is 

very useful for local labels. 



org 



code 



data 

even 

odd 
end 
equ or 

list 
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For example: x?0: bsr pmsg 
illegal Produces an illegal machine language instruction, 
globl Defines the following label as global when the "I" option of the 

assembler is chosen. 

Once you've assembled your program, the program code is in memory. 
Using the "h" instruction, you can find out how large the program is and 
where it is located in memory. The beginning and end address is given in 
hex and the length is given in decimal (according to the last executed 
operations): 

Work The memory area defined in the beginning 

Src Text in memory 

RelC Relocation table of the program 

RelD Relocation table of the memory area 

Code Program code produced 

Data The program's memory area 

You'll find your program in memory at the location given by Code. It's a 
pain to have to enter this address whenever you want to start the program. 
It makes good sense to mark the beginning of the program with a label 
(for example, "run:"). You can use the "g" instruction to run the program 
as follows: 

grun 

The "g" (Go) instruction is one of SEKA's debugger instructions. Here's 
an overview: 

x Output all registers 

xr Output and change of registers (ie xdO) 

gn Jump to address n. You'll be asked for break points, addresses at 

which the program should terminate, 
jn This is similar to the one above — a JSR is used to jump into 

the program. The program must end with a RTS instruction, 
qn Output the memory starting at address n. You can also specify 

the word length. 

For example: q.w $10000 
nn Disassembled output starting at address n 

an Direct assembling starting at address n. Direct program instruc- 

tions are entered. 
mn Modify the contents of memory starting at address n. Here too, 

the word length can be given. You can terminate input with the 

<Esc> key. 
sn Executes the program instruction that the PC points to. After 

you enter this instruction, n program steps are executed. 
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Fill a memory area. You can choose the word width. All the 

needed parameters are asked for individually. 

Copies one memory area to another. All the needed parameters 

are asked for individually. 

Outputs the value of an expression or a label 

For example: ? run+$ 1000-256 

Sets an instruction sequence that is passed to the program when 

it starts as if it was started from CLI with this sequence 

Leave the SEKA assembler after being asked if you are sure. 



ample. You can also use them in programming. The following operations 
work in SEKA: 



+ 


Addition 


- 


Subtraction 


* 


Multiplication 


/ 


Division 


& 


Logical AND 


J 


Logical OR 


~ 


Exclusive OR (XOR) 



These operations can also be combined. You can choose the counting 
system. A "$" stands for hexadecimal, "@" for octal, and "%" for binary. 
If these symbols aren't used, the number is interpreted as a decimal num- 
ber. 

Let's go back to the debugger. As mentioned, after entering "g Address", 
you'll be asked for break points. You can enter up to 16 addresses at 
which the program halts. If you don't enter break points, but instead hit 
<Return>, the program must end with an ILLEGAL instruction. If it ends 
instead with a RTS, the next return address from the stack is retrieved and 
jumped to. This is usually address 4 which causes SEKA to come back 
with "** Illegal Instruction at $000004", but there's no guarantee that it 
will. You're computer can end up so confused that it can't function. 

The SEKA program puts an ILLEGAL instruction in the place specified 
as break points after saving the contents of these locations. If the pro- 
cessor hits an illegal instruction, it jumps back to the debugger by using 
the illegal instruction vector that SEKA set up earlier. Then SEKA 
repairs the modified memory locations and then displays the status line. 
Here you can find out where the program terminated. 

Using break points is a good technique for finding errors in the program. 
You can, for example, put a break point in front of a routine that you're 
not sure about and start the program. When the program aborts at this 
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spot, you can go through the routine step by step using the "s" option. 
Then you can watch what happens to the status line after each instruction 
and find the mistake. 

Program errors are called bugs. That's why the program which finds them 
is called a debugger. 
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4. Our First Programs 



You're getting pretty far along in your knowledge of machine language 
programming. In fact, you're to the point where you can write programs, 
and not just programs for demonstration purposes, but ones which serve a 
real function. We're assuming that you have the AssemPro assembler and 
have loaded it 

If you're using a different assembler, a few things must be done differ- 
ently. We covered those differences already in the chapter on the different 
assemblers. 

We've written the example programs as subroutines so they can be tried 
out directly and used later. After assembling the program, you can put the 
desired values in the register. Then you can either single-step thru the pro- 
grams or run the larger programs and observe the results in the registers 
directly. (Using the SEKA assembler you can type "j Programname" to 
start the program. Then you can read the results from the register directly, 
or use "q Address" to read it from memory.) 

Let's start with an easy example, adding numbers in a table. 



4.1 Adding tables 



Imagine that you have numbers in memory that you'd like to add. Let's 
assume that you have five numbers whose length is one word each. You 
want their sum to be written in register DO. The easiest way to do this is: 



;<4.ia) 






addingl: 






clr.l 


DO 


jErase DO ( = 0) 


move 


table.dO 


;First entry in DO 


add 


table + 2,d0 


;Add second entry 


add 


table + 4,d0 


;Add third entry 


add 


table + 6,d0 


;Add fourth entry 


add 


table + 8,d0 


;Add fifth entry 


rts 




jReturn to main program 


table: dew 2, 


,4,6,8,10 




end 
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Try out the program using the debugger by single stepping thru the pro- 
gram until you get to the RTS instruction (left Amiga T). (SEKA owners 
use "j addingl"). You see that data register DO really contains the sum of 
the values. 

The method above only reads and adds numbers from a particular set of 
addresses. The Amiga's processor has lots of different sorts of addressing 
modes that give us a shorter and more elegant solution. Let's add a 
variable to the address of the table, so that the program can add different 
tables. 

Let's put the address of the table in an address register (for example, AO) 
instead. This register can be used as a pointer to the table. You must use 
move.l since only long words are relocatable. By using a pointer to a 
table you can use indirect addressing. You can change the expression 
"table+x"to"x(aO)". 



;<4.ib) 






addingl: 






clr.l 


DO 


JErase DO ( = 0) 


move.l 


#table, aO 


;Put table address in AO 


move 


0(aO),dO 


;Put first entry in DO 


add 


2 (aO),dO 


;add second entry 


add 


4(a0),d0 


;add third entry 


add 


6(a0),d0 


;Add fourth entry 


add 


8(a0),d0 


;Add fifth entry 


rts 




jReturn to main program 


table: dew 2, 


,4,6,8,10 





end 

Assemble this program, load it into the debugger. Then single step (left- 
Amiga T) thru this program and you'll see that this program adds five 
numbers in order just like the last one. The reason you used a step size of 
two for the offset is that words are two bytes long. AssemPro also de- 
faults to relocatable code so that you must move #table as a long word. 

Let's improve the program more by using "(a0)+" instead of "x(a)'\ This 
way, every time you access elements of the table, the address register AO 
is automatically incremented by the number of bytes that are read (in this 
case two). The difference between this and the last example is that here 
the register's contents are modified. The pointer is to the next unused byte 
or word in memory. 

Let's make it even better. Let's make the number of words to be added to 
a variable. You'll pass the number in register Dl. Now you need to do a 
different sort of programming, since you can't do it with the old methods. 
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Let's use a loop. You need to add Dl words. You can use (a0)+ as the ad- 
dressing method (Address register indirect with post increment), since this 
automatically gets you to the next word. 

Now for the loop. You'll have Dl decremented by one every time the 
contents of the pointer are added. If Dl is zero, then you're done. Other- 
wise, you need another addition. The program looks like this: 



;(4.io 








adding2: 








clr.l 


dO 


jErase DO 




move.l 


#table, aO 


;Put table address in AO 




move 


#$5,dl 


;Put number of entries in dl 


loop: 






jLabel for loop beginning 




add 


(aO) +,d0 


;Add a word 




subq 


#l,dl 


jDecrement counter 




bne 


loop 


jContinue if non-zero 




rts 




;Else done 


table: 


dew 2, 

end 


,4,6,8,10 





Let's take a close look at this program. Load the pointer AO with the 
address of the data and the counter Dl with the number of elements. Then 
you can single step thru the program and watch the results. Make sure not 
to run the final command, the RTS command, because otherwise a return 
address is popped from the stack, and the results of this are unpredictable. 
(SEKA owners can use "x pc" to point the program counter to "adding2". 
You can then step through the program using the "s" command and watch 
the results.) 

To finish up this example, you're assigning a little homework. Write the 
program so that it adds single bytes or long words. Try to write a 
program that takes the first value in a table and subtracts the following 
values. For example, the table 

table: dew 50,8,4,6 

should return the value 50-8-4-6, ie 32 ($20). 
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4.2 Sorting a table 



Let's keep working with tables. You don't want to just read data from one 
this time. You want to change it. You'll sort the table in ascending order. 

You need to decide how to do the sorting. The simplest method is to do 
the following. 

Compare the first and the second value. If the second value is larger than 
the first one, things are OK so far. Do the next step, compare the second 
and third values, and so on. If you come to the final pair and in each case 
the preceding value was smaller than the following value, then the sorting 
is done (it was unnecessary). 

If you find a pair where the second value is smaller than the first, the two 
values are exchanged. You then set a flag (here let's use a register) that is 
checked once you're done going through the table. If it is set, the table 
probably isn't completely sorted. You then erase the flag and start again 
from the beginning. If the flag is still zero at the end, the sorting is 
complete. 

Now let's write a program to do this. First let's figure out the variables 
you need. You'll use registers for the variables. You need a pointer to the 
table you're sorting (AO), a counter (DO) and a flag (Dl). While the 
program is running, change these values, so you'll need two more regis- 
ters to store the starting values (address and the number of table entries). 
You'll use Al and D2. 

Let's start writing the program, each section will be written and then 
explained. Then the complete program will be given. You put the table's 
address in Al and the number of entries in D2. 

;(4.2A) part of sort routine 

sort: JStart address of the program 

;Load pointer with address 
;Copy pointer to working register 
JNumber in the counter 
;Copy number of elements 
jCorrect counter value 
jErase flag 

table: dew 3,6,8,9,5 

end 



move.l 


#table,al 


move.l 


al,aO 


move.l 


#5,d2 


move . 1 


d2,d0 


subq 


#2,d0 


clr 


dl 
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Now the preparations are complete. The pointer and the counter are ready 
and the flag is cleared. The counter is decremented by two because you 
want to use the DBRA command (take off one) and only X-l comparisons 
are needed for X numbers (take off one more). 

Next let's write the loop that compares the values. You compare one 
word with another. It looks like this: 

loop: 

move 2(a0),d3 ;Next value in Register D3 

cmp (a0),d3 jCompare values 

You need to use register D3 because CMP ( AO ) ,2 ( AO ) isn't a legal 
choice. If the second value is greater than or equal to the first value, you 
can skip an exchange. 

bcc noswap jBranch if greater than or equal 

;to 

Now you need to do the exchanging (unfortunately you can't use exc 
2 ( a ) , ( a ) since this form of addressing doesn't exist). 

doswap: 

move (aO),dl ;Save first value 

move 2(a0),(a0) ;Copy second into first word 

move dl,2 (aO) ;Move first into second 

moveq #l,dl ;Set flag 

noswap: 

Now increment the counter and continue with the next pair. You do this 
until the counter is negative. 

addq.l #2,a0 ;Pointer+2 

dbra dO,loop ;Continue looping until the end 

Now you'll see if the flag is set. You start again at the beginning if it is. 



tst 


dl 


;Test flag 


bne 


sort 


;Not finished sorting yet ! 


rts 




jOtherwise done. Return. 



If the flag is zero, you're done, and the subroutine ends. You jump back 
to the main program using the RTS command. 

Now a quick overview of the complete program. 
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(4.2B) 






sort: 








move.l 


#table,al 




move.l 


al,aO 




move.l 


#5,d2 




move.l 


d2,d0 




subq 


#2,d0 




clr 


dl 


I.; op: 








move 


2(a0),d3 




cmp 


(a0),d3 




bcc 


noswap 


doswap: 








move 


(aO).dl 




move 


2(a0),(a0) 




move 


dl,2 (aO) 




moveq 


#l,dl 


noswap: 








addq.l 


#2,a0 




dbra 


dO,loop 




tst 


dl 




bne 


sort 




rts 





jStart address of the program 
;Load pointer with address 
;Copy pointer to working 
Jregister 

jNumber in the counter 
;Copy number of elements 
jCorrect counter value 
;Erase flag 



;Next value in Register D3 

jCompare values 

jBranch if greater than or equal 

;to 



JSave first value 
JCopy second into first word 
;Move first into second 
;Set flag 



;Pointer + 2 

;Continue looping until the end 

;Test f±ag 

;Not finished sorting yet ! 

jOtherwise done. Return. 



table: dew 10,8,6,4,2 ; When finished, acceding 
end 

To test this subroutine, assemble the routine with AssemPro, save it and 
then load it into the debugger. The table is directly after the RTS, notice 
its order. Set a breakpoint at the RTS, select the address with the mouse 
and press left-Amiga-B sets a breakpoint in AssemPro. Start the program 
then redisplay the screen by selecting "Parameter-Display-Dissassem-bled" 
and examine the order of the numbers in the table, they should now be in 
ascending order. 

You use several registers in this example for storing values. Usually in 
machine language programming your subroutines cannot change any 
registers or can only change certain registers. For this reason, there is a 
machine language command to push several registers onto the stack at the 
same time. This is the MOVEM ("MOVE Multiple") command. If you 
insert this command twice into your program, then you can have the 
registers return to the main program with the values they had when the 
subroutine was called. To do this, you need one more label. Let's call it 
"start"; the subroutine is started from here. 
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start: 

movem.l d0-d7/a0-a6,- (sp) ;Save registers 

sort: 

etc... 



bne sort ;Not finished sorting yet ! 

movem.l (sp) + f d0-d7/a0-a6 ;Retrieve registers 
rts JFinished! 

This powerful command moves several registers at the same time. You 
can specify which registers should be moved. If you want to move the 
Dl, D2, D3, D7, A2 and A3 registers, just write 

movem.l dl-d3/d7 /a2-a3,- ( sp) 

Before you quit sorting, do one little homework assignment. Modify the 
program, so that it sorts the elements in descending order. 
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4.3 Converting number systems 



As we mentioned in the chapter on number systems, converting numbers 
from one base to another can be rather difficult. There is another form of 
numeric representation — as a string that can be entered via the keyboard or 
output on the screen. 

You want to look at some of the many conversions possible and write 
programs to handle the task. You'll start by converting a hex number into 
a string using binary numbers and then print the number value in hex. 



4.3.1 Converting hex to ASCII 

First you need to set the start and finish conditions. In this example, let's 
assume that data register Dl contains a long word that should be con- 
verted into an 8-digit long string of ASCII characters. You'll write it to a 
particular memory location so that you can output it later. 

The advantage of using hex instead of decimal is pretty clear in this 
example. To find out the hexadecimal digit for a particular spot in the 
number, you just need to take the corresponding 4 bits (half byte) and do 
some work on it. A half byte (also called a nibble) contains one hex digit. 

You'll work on a half byte in D2. To convert this to a printable character, 
you need to use the correct ASCII code. The codes for the 16 characters 
that are used as hex digits are the following: 

0123456789ABCDEF 
$30 $31 $32 $33 $34 $35 $36 $37 $38 $39 $41 $42 $43 $44 $45 $46 



To convert the digits 0-9, you just need to add $30. For the letters A-F 
that correspond to the values 10-15, you need to add $37. The program to 
evaluate a half byte must make a distinction between values between 
and 9 and those between A and F and add either $30 or $37. 

Now let's write a machine language subroutine that you'll call for each 
digit in the long words hex representation. 



70 



Abacus 



4. Our First Programs 



nibble: 






and 


#$0f,d2 


JJust keep low byte 


add 


#$30,d2 


;Add $30 


cmp 


#$3a,d2 


;Was it a digit? 


bcs 


ok 


;Yes: done 


add 


#7,d2 


;Else add 7 



ok: 



rts 



;Done 



This routine converts the nibble in D2 to an ASCII character that corres- 
ponds to the hex value of the nibble. To convert an entire byte, you need 
to call the routine twice. Here is a program to do this. The program 
assumes that A0 contains the address of the buffer that the characters are 
to be put in and that Dl contains the byte that is converted 



;(4.3.1a 


) bin- 


-hex 




» 








Jyour program 




lea 




buffer, aO 


jPointer to buffer 




move 




#$4a,dl 


;Byte to be converted (Example) 




bsr 




byte 


;and convert 




rts 






jmore of your program 


byte: 












move 




dl,d2 


jMove value into D2 




lsr 




#4,d2 


jMove upper nibble into lower 
Jnibble 




bsr 




nibble 


jConvert D2 




move. 


.b 


d2,(a0) + 


JPut character in buffer 




move 




dl,d2 


jValue in D2 




bsr 




nibble 


jConvert lower nibble 




move, 


.b 


d2,(a0) + 


;and put it in buffer 




rts 






;Done 


nibble: 












and 




#$0f,d2 


JJust keep low byte 




add 




#$30,d2 


;Add $30 




cmp 




#$3a,d2 


;Was it a digit? 




bcs 




ok 


;Yes: done 




add 




#7,d2 


;Else add 7 



ok: 



rts 



JDone 



buffer: 



blk.b 9,0 
end 



jSpace for long word data 



To test this subroutine, use AssemPro to assemble the routine, save the 
program and load it into the debugger. Next set a breakpoint at the first 
RTS, to set the breakpoint in AssemPro select the correct address with 
the mouse and press the right- Amiga-B keys. Start the program and watch 
the contents of D2, it is first $34 (ASCII 4) and finally $41 (ASCII A). 
Select "Parameter-Display-HEX-Dump" and you'll see that 4 A has been 
moved into the buffer. 
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This is how the routine operates. First, you move the value that you 
wish to convert into D2. Then you shift the register four times to the 
right to move the upper nibble into the lower four bits. After the 
subroutine call, you use "move.b d2,(a0)+" to put the HI nibble in the 
buffer. Then the original byte is put in D2 again. It is converted. This 
gives us the LO nibble as an ASCII character in D2. You put this in the 
next byte of the buffer. 

The buffer is long enough to hold a long word in characters and closing 
the null byte. The null byte is usually required by screen output routines. 
Screen output will be discussed in a later chapter. Now let's worry about 
converting a long word. 

When converting a long word, you need to be sure to deal with the 
nibbles in the right order. Before calling the "nibble" routine for the first 
time, you need to move the upper nibble into the lower four bits of the 
long word. You need to do this without losing anything. 

The LSR command isn't very good for this application. If you use it, 
you'll lose bits. It's better to use the rotation commands like ROR or 
ROL, since they move the bits that are shifted out, back in on the other 
side. 

If you shift the original long word in Dl four times to the left, the upper 
four bits are shifted into the lower four bits. Now you can use our 
"nibble" routine to evaluate it and then put the resulting ASCII character 
in the buffer. You repeat this eight times and the whole long word has 
been converted. You even have Dl looking exactly the way it did before 
the conversion process began! 



;(4.3.1B) bin-hex-2 

hexlong: 

lea buffer, aO 
move.l #$12345678,dl 
move #7,d3 



jPointer to the buffer 

;Data to convert 

jCounter for the nibbles: 8-1 



loop: 



rol 


#4,dl 


JMove upper nibble into lower 


move 


dl,d2 


jWrite in D2 


bsr 


nibble 


;And convert it 


move.b 


d2,(a0) + 


Character in buffer 


dbra 


d3,loop 


jRepeat 8 times 


rts 




jFinished ! 


nibble: 






and 


#$0f,d2 


;Just keep low byte 


add 


#$30,d2 


;Add $30 


cmp 


#$3a,d2 


;Was it a digit? 


bcs 


ok 


;Yes: done 


add 


#7,d2 


jElse add 7 
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ok: 

rts jDone 

buffer: 

blk.b 9,0 jSpace for long word, null byte 

end 

To test this subroutine, use AssemPro to assemble the routine, save the 
program and load it into the debugger. Next set a breakpoint at the first 
RTS, to set the breakpoint in AssemPro select the correct address with 
the mouse and press the right- Amiga-B keys. Start the program and when 
it is finished redisplay the output by selecting "Parameter-Display-HEX- 
dump" so you can examine the new buffer contents. 

You'll find that there's an error in the program — the buffer contains the 
digits "56785678" instead of "12345678". Try to find the error! 

Have you found it? This is the sort of error that causes you to start 
pulling your hair out. This sort is hard to find. The assembler assumes 
that the rotation operation should be done on a word, because the ".1" was 
left off. As a result, only the lower word of Dl was rotated — so you get 
the same value twice. If you change it to "rol.l", things work just right. 

This error shows how easy it is to convert the program above into one 
that converts four digit hex numbers into ASCII characters. Just leave off 
the ".1" on the "rol" command and change the counter from seven to three. 
The program is done. 

Now for a little homework: change the program so that it can handle six 
digit hex numbers (Dl doesn't necessarily have to stay the same ...)! 

Now let's look at a different conversion problem: converting a four digit 
decimal number. 



4.3.2 Converting Decimal to ASCII 

It's not quite as easy to convert to decimal as hex. You can't group the 
bits to form individual digits. You need to use another method. 

Let's look at how a decimal number is constructed. In a four digit num- 
ber, the highest place is the thousand's place, the next is the hundred's 
place, etc... 
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If you have the value in a register and divide by 1000, you'll get the value 
that goes in the highest place in the decimal number. Since the machine 
language command DIV not only gives us the result of division but also 
gives us the remainder, you can work with the remainder quite easily. 
You divide the remainder by 100 to find the hundred's place, divide the 
remainder of this by ten and get the ten's place, and the final remainder is 
the one's place. 

This isn't so hard after all! Here's the program that follows the steps 
above to fill the buffer with Dl's ASCII value. 



main: 



lea 
move 
jsr 
illegal 



buffer, aO jPointer to the buf f er 

#1234,dl jNumber to convert 

deci_4 ;test subroutine 

Jroom for break point 



deci 4: 



Subroutine - four digit numbers 



divu 


#1000,dl 


bsr 


digit 


divu 


#100,dl 


bsr 


digit 


divu 


#10,dl 


bsr 


digit 



jDivide by 1000 

jEvaluate result-move remainder 

jDivide by 100 

jEvaluate result and move 

remainder 

JDivide by 10 

;Evaluate result-move remainder 



jEvaluate the remainder directly 



digit: 



add #$30,dl 


;Convert result into ASCII 


move.b dl, 


(a0) + 


jMove it into buffer 


clr dl 




JErase lower word 


swap dl 




jMove the remainder down 


rts 




jReturn 


ffer:blk.b5,0 




jReserve bytes for result 


end 







To test this subroutine, use AssemPro to assemble the routine, save the 
program and load it into the debugger. Next set a breakpoint at the illegal 
instruction. To set the breakpoint in AssemPro select the correct address 
with the mouse and press the right- Amiga-B keys. This break point stops 
the program. Start the program and when it is finished redisplay the out- 
put by selecting "Parameter-Display-HEX-dump" so you can examine the 
ASCII values now in the buffer. 

You use a little trick in this program that is typical for machine language 
programming. After calling "digit" three times from the subroutine 
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"deci_4", you go right into the "digit" subroutine. You don't use a BSR 
or JSR command. Once the processor hits the RTS command, it returns 
to the main program, not the "deci_4" subroutine. Doing this, you save a 
fourth "bsr digit" command and an "rts" command for the "deci_4" 
routine. 

Try the program out Make sure that you use values that are smaller than 
9999, because otherwise strange things can happen. 

Now let's reverse what you've been doing and convert strings into binary 
numbers. 



4.3.3 Converting ASCII to hex 

In a string, each hex digit represents a half byte. You just need to write a 
program that exactly reverses what the hex conversion program did. 

You have two choices 

1 . The number of hex digits is known in advance 

2. The number is unknown 

The first is easier to program, but has the disadvantage that if, you 
assume the strings are four digits in length and want to enter the value 1, 
you must enter 0001. That is rather awkward, so you'll use the second 
method. 

Let's convert a single digit first. You'll pass a pointer to this digit in 
address register A0. You want the binary value to come back in data 
register DO. 

The program looks like this: 

move.l #string,a0 ; this example 
jsr nibblein ; test routine 
nop ; set breakpoint here 

nibblein: ;* Convert the nibble from (A0) 

clr.l dO jErase DO 

move.b (a0)+,d0 ;Get digit, increment A0 

sub #'A',dO ;Subtract$41 

bcc ischar ;No problem: In the range A-F 

add #7,d0 ;Else correct value 

ischar: 

add #10, dO ;Correct value 
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rts 
string", dc.b ' B ' ,0 Jcharacter to convert 

end 

To test this subroutine, use AssemPro to assemble the routine, save the 
program and load it into the debugger. Next set a breakpoint at the first 
NOP, to set the breakpoint in AssemPro select the correct address with 
the mouse and press the right- Amiga-B keys. Start the program and watch 
the contents of DO. 

Let's see how the program works. A0 points to a memory location that 
contains the character "B" that is represented by the ASCII value $42. 
This number is loaded into DO right after this register is erased. 

After subtracting $41, you end up with the value $1. Now you're almost 
done. Before returning to the main program, you add 10 to get the correct 
value 11, $B. 

If the buffer has a digit in it, the subtraction causes the register to become 
negative. The C flag is set. Let's take the digit 5 as an example. 

The ASCII value of 5 is $35. After subtracting $41, you end up with -12 
and the C flag is set. In this case, you won't branch with the BCC com- 
mand. Instead you'll add 7 to get -5. Then 10 is added, and you end up 
with five. Done! 

This routine has a disadvantage. If an illegal character is given, one that 
doesn't represent a hex digit, you'll get some nonsense result. Let's ig- 
nore error checking for the moment though. 

Let's go on to multi-digit hex numbers. The first digit that you convert 
has the highest value and thus represents the highest nibble. To allow for 
this and to allow for an arbitrarily long number (actually not arbitrarily 
long, the number should fit in a long word — so it can only be eight digits 
long), you'll use a trick. 

Take a look at the whole program. It handles the calculations and puts the 
result in Dl. It assumes that A0 is a pointer to a string and that this 
string is ended by a null byte. 

hexin: ;Converting a hex number 

clr.l dl ;First erase Dl 

move.l #string, aO ;Address of the string in A0 

jsr hexinloop ; test subroutine 
nop ; set break point here 

hexinloop: 

76 



Abacus 



4. Our First Programs 



tst.b 


(aO) 


;Test digit 


beq 


hexinok 


JZero, then done 


bsr 


nibblein 


jConvert digit 


lsl.l 


#4,dl 


jShift result 


or.b 


dO,dl 


JInsert nibble 


bra 


hexinloop 


;And continue 


hexinok: 






rts 






nibblein: 




jConvert the nibble from (AO) 


clr.l 


dO 


;Erase DO 


move.b 


(aO)+,dO 


;Get digit, increment AO 


sub 


#'A',dO 


;Subtract $41 


bcc 


ischar 


;No problem: In the range A-F 


add 


#7,d0 


;Else correct value 


ischar: 






add 


#10,d0 


;Correct value 


rts 







string: DC.B "56789ABC ' ,00 
end 



;8 digit string, null byte 
; to be converted 



To test this subroutine, use AssemPro to assemble the routine, save the 
program and load it into the debugger. Next set a breakpoint at the NOP, 
to set the breakpoint in AssemPro select the correct address with the 
mouse and press the right- Amiga- B keys. Start the program and watch the 
contents of Dl, the hex value is placed in this register. 

The trick is to shift left four times, to shift one nibble. In this way, the 
place of the last digit is incremented by one and there is room for the 
nibble that comes back from the "nibblein" routine. The program uses the 
TST.B instruction to check for the null byte at the end of the string, 
when it encounters the null byte the program ends. The result is in the 
Dl long word already! 

To do some error checking, you need to make some changes in the pro- 
gram. You'll do this right after you come back from the "nibblein" 
routine with the value of the current character. 

If the value in DO is bigger than $F, there is an error. You can detect this 
in several ways. You chose the simplest one — you'll use CMP #$10,D0 
to compare DO with $10. If it is smaller, then the C flag is set (since 
CMP uses subtraction) and everything is fine. If C is zero, there is an 
error. 

You can use this trick to skip the test for a null byte, since it's an invalid 
character as well. The program looks like this: 
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;(4_3_3C) hex-conv2 
hexin: 



Optional disk name 
jConverting a hex number 



clr.l 


dl 


jFirst erase Dl 


move.l 


#string, aO 


jAddress of the string in AO 


jsr . 


hexinloop 


Jtest subroutine 


nop 




; set break point here 


hexinloop: 






bsr 


nibblein 


jConvert digit 


cmp 


$10,d0 


jTest if good 


bcc 


hexinok 


JNo, then done 


lsl.l 


#4,dl 


JShift result 


or.b 


dO,dl 


JInsert nibble 


bra 


hexinloop 


;And continue 


hexinok: 






rts 






nibblein: 




jConvert the nibble from (AO) 


clr.l 


dO 


jErase DO 


move.b 


(aO)+,dO 


;Get digit, increment AO 


sub 


#'A',dO 


JSubtract $41 


bcc 


ischar 


JNo problem: In the range A-F 


add 


#7,d0 


;Else correct value 


ischar: 






add 


#10,d0 


jCorrect value 


rts 







string: DC.B "56789ABC ' ,00 
end 



;8 digit string ending with a 
; null byte to be converted 



To test this subroutine, use AssemPro to assemble the routine, save the 
program and load it into the debugger. Next set a breakpoint at the NOP, 
to set the breakpoint in AssemPro select the correct address with the 
mouse and press the right- Amiga-B keys. Start the program and watch the 
contents of Dl, the hex value is placed in this register. 

This is the method for converting hex to binary. If you convert decimal to 
binary, the conversion is not much harder. 



4.3.4 Converting ASCII to decimal 

You can use a very similar method to the one used above. Since you're 
not sure how many digits there are, you'll use a similar method for 
putting digits of a number in the next place up. You can't do this with 
shifting, but you can multiply by 10 and add the value of the digit. 

Here's the program for converting decimal numbers. 
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decin: 




JConverting a decimal number 


clr.l 


dl 


JFirst erase Dl 


move.l 


#string,aO 


;The string to convert 


jsr 


decinloop 


;Test subroutine 


nop 




;Breakpoint here 


decinloop: 






bsr 


digitin 


jConvert digit 


cmp 


#10,d0 


;Test, if valid 


bcc 


decinok 


;No, then done 


mulu 


#10,dl 


;Shift result 


add 


dO,dl 


;insert nibble 


bra 


decinloop 


;And continue 


decinok: 






rts 




;End of conversion 


digit in". 




JConverting the nibble from 


clr.l 


dO 


jErase DO 


move.b 


(aO)+,dO 


;Get digit, increment AO 


sub 


#'0',d0 


;Subtract $30 


rts 






string: dc.b ' 


123456' 


JASCII decimal string to com 



end 

To test this subroutine, use AssemPro to assemble the routine, save the 
program and load it into the debugger. Next set a breakpoint at the NOP, 
to set the breakpoint in AssemPro select the correct address with the 
mouse and press the right-Amiga-B keys. Select "Parameter-Output 
numbers-Decimal" so the registers are displayed as decimal numbers. 
Then start the program and watch the contents of Dl, the decimal value is 
placed in this register. 

This program can only convert numbers up to 655350, although the hex 
conversion routine can go higher. That's because the MULU command 
can only multiply 16-bit words. The last multiplication that can be done 
correctly is $FFFF*10--65535*10, which gives us the value 655350. 
Normally this is a large enough range, so you won't complicate the pro- 
gram further. 
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5 Hardware Registers 



You can get information about hardware functions without using library 
functions. You can use the hardware registers instead. These are memory 
locations at particular addresses that are neither in RAM nor in ROM. 
They are direct interfaces between the processor and its peripheral devices. 

Each device has a number of hardware registers that the processor accesses 
to control graphics, sound and input/output. There are lots of possibilities 
for assembly language programmers. We'll only be able to go into a few 
examples. 

The registers are generally used in byte- wise fashion. You'll find an 
example in the next chapter. 



5.1 Checking for special keys 



Load AssemPro and enter the debugger, select "Parameter-Display-From 
Address" and enter $BFEC00. Next select "Parameter-Display-HEX- 
Dump" to display the memory. (To use the SEKA assembler or a similar 
monitor program, enter "q $bfec00'\) 

You'll see a byte-wise listing of the addresses starting at $BFEC00 in 
which two bytes always repeat. These two bytes represent the status of 
two hardware registers. 

The mirroring occurs because not all the address bits are used in decoding 
the address. In addressing this register, only the upper two bytes of the 
address and the low bit, bit 0, are used. The address of the two registers 
goes like this: $BFECxx, where the lower address byte xx doesn't contain 
any information in bits 1-7. Only bit contains information about the 
desired register. You'll find this odd form of addressing with most hard- 
ware registers. 

Let's look at the information in these registers. Let's look at the second 
register, $BFEC01. Hold down the <Alt> key and select "Parameter- 
Display -HEX-Dump" to re-display the screen. (SEKA owners must enter 
"q $bfec00" and press the <Alt> key right after pressing the <Return> 
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key.) You'll see that contents of every two bytes ($BFEC01, $BFEC03, 
etc...) have been changed to $37. This is the status of the special keys. 
This is also true for the other special keys. The following keys produce 
the bytes: 



Shift left 


$3F 


Shift right 


$3D 


Control 


$39 


Alternate 


$37 


Amiga left 


$33 


Amiga right 


$31 



You can use this register to have a machine language program check if 
one of these keys was pressed and then respond by calling or ending a 
function. A program section might look like this: 



skeys 


= $bfec01 








cmp.b 


#$37, skeys 


Alternate pressed? 




beq 


f unctionl 


;Yes! 




cmp.b 


#$31, skeys 


Jor right Amiga? 




beq 


f unction2 


;Yes! 

;and so on... 
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5.2 Timing 



If you want to find out how much time elapsed between two events, you 
can use a hardware register to keep track of time quickly and precisely. 
The Amiga contains just such a time keeper: the I/O port componant. 
This chip has a 24 bit wide counter that has a 60 Hertz clock. 

These 24 bits can't be read at once, for instance with a MOVE.L com- 
mand, because the register is divided into three bytes. The low byte is at 
address $BFE801, the middle at $BFE901, and the high byte with bits 16- 
23at$BFEA01. 

Here's an example of a way to use this register: finding out how long a 
subroutine takes to run. 



test: 



bsr 


gettime 


move.l 


d7,d6 


bsr 


routine 


bsr 


gettime 


sub.l 


d6,d7 



nop 



;Put current timein D7 

;Save it in D6 

jRoutine to be timed 

;Get the time again 

jElapsed time in 

;l/50 seconds is in D7 ! 

; set breakpoint here to stop 



routine: 




; test routine 


move 


#500,d0 


; delay counter 


loop: 






dbra 


d0,loop 


Jcount down 


rts 






gettime: 






move.b 


$bfea01,d7 


;HI-ByteinD0 


lsl.l 


#4,d7 


;Shift twice by 4 bits, 


lsl.l 


#4,d7 


;(8 bits shifted) 


move.b 


$bfe901,d7 


;Get MID-Byte 


lsl.l 


#4,d7 




lsl.l 


#4,d7 


;Shift again 


move.b 


$bfe801,d7 


;Get the LO-Byte 


rts 




;Done 
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5.3 Reading the mouse - joystick 



There are two hardware registers for the mouse and the joystick. They 
contain the state (or the position) of these input devices. It's interesting 
that the same port is used with both the mouse and the joystick even 
though they work completely different. 

The joystick has four switches that are closed during movement and give 
off a potential (-) that is related to the movement of the joystick/mouse. 
The mouse's movements give off lots of quick signals — two for horizon- 
tal and two for vertical movement. 

The computer must keep an eye on the ports so that it can evaluate the 
signals and calculate the new mouse position. This isn't the work of the 
processor though; it already has too much to do. 

You find the status of the mouse/joystick port at address $DFF00A for 
port 1 and $DFF00C for port 2. The information in these words is for 
vertical mouse movement in the lower byte and for horizontal movement 
in the upper byte. 

AssernPro owners be careful! Don't read these addresses, because for some 
reason that causes the computer to crash. This looks interesting (the 
screen begins to dance), but you can only recover by pressing <Reset> 
and loosing all of your data. 

To read this register, let's write a short program. 



;<5.3a: 


) mouse 






test: 










jsr 


run 


JTest subroutine 




jmp 


test 


Jcontinute until broken 




nop 




JBreakpoint here 


joy = 


$dff00a 






run: 










move 


joy,d6 


;Data Item 1 in D6 




move 


joy+2,d7 


;Data Item 2 in D7 




jmp 


run 


;rts for Seka and other 



end 
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If you assemble the program and start Breakable in the debugger (SEKA - 
"j run"), D6 and D7 contain the contents of the two registers. Move the 
mouse a bit and watch the register contents. 

As you see, the value in D6 is different. If you just move the mouse 
horizontally, only the lower byte's value is different, if just moved ver- 
tically only the upper byte is different. 

You are not getting the absolute position of the mouse pointer on the 
screen. You can see that easily by moving the mouse into the upper left 
corner, then reading the value by restarting the program, and then move 
the mouse left again. As you can see, the register's contents are always 
relative. 

Change the program as follows: 

;(5.3B) mouse difference 



JTest subroutine 
Jcontinute until broken 
;Breakpoint here 



;01d posit ion in D6 
;New position in D7 
;Dif ference in D6 
;rts for Seka and other 



test: 








jsr 


run 




jmp 


test 




nop 




joy = 


= $dff00a 




run: 








move 


d7,d6 




move 


joy,d7 




sub 


d7,d6 




jmp 


run 



end 



Start Breakable (right- Amiga- A) in the AssemPro debugger and watch D6, 
the result is zero or D7. (SEKA owners have to start the program two 
times. The result in D6 is zero.) If you move the mouse, D6 contains the 
difference between the old and new positions since the start. You'll find 
the vertical and horizontal position of the mouse relative to the last time 
you looked. In this way, you can use this register to find the relative 
mouse movement between two checks. 

Now to check the joysticks. Put a joystick in port 2 and change the 
address $DFF00A to $DFF00C in the program. Start Breakable in the 
AssemPro debugger and watch D6, the result is zero or D7. (SEKA 
owners have to start the program two times. The result in D6 is zero.) 

Move the joystick up. You'll get the value $FF00. One was subtracted 
from the upper byte. Let the joystick loose. This time you get the value 
$100 — one is added. You'll get the same effect when you move the joy- 
stick left — after you let go, one is subtracted. 
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up 


$FFOO 


down 


$FFFF 


left 


$0100 


right 


$0001 
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The individual movements and their effects on the joystick program are: 

HI-Byte-1 
LO-Byte-1 
HI-Byte+1 
LO-Byte +1 

These values aren't terribly reliable. If you move the joystick a lot and 
then look at the value, you'll find a crazy value in D6. This is because 
the input driver thinks that a mouse is attached. Nevertheless, this is the 
quickest way to read a joystick. In this way, an external device that gives 
off evaluatable TTL signals can be connected to the port and watched by a 
machine language program. 

Now you just need to find out whether the fire button has been pressed, 
and you'll know how to get all the information you need from the 
joystick. The button's state is in bit 7 of the byte that is in memory 
location $BFE001. If the bit is set, the button wasn't pressed. That's true 
for the joystick connected to port 2. Bit 6 of this byte contains the 
button's state when the joystick is in port 1 or the state of the left mouse 
button. 

Let's stay on port 2. You can test bit 7 to execute a function when the 
joystick button is pressed without any problems. Bit 7 is the sign bit. 
You can use this program segment: 

tst.b $bfe001 ;Was fire button 2 hit? 
bpl fire ;Yes ! Branch 

The TST.B instruction tests the addressed byte and sets the Z and the N 
flag. If the N flag is set, you know that bit 7 of the tested byte is set. 
Since the fire button turns on LO potential, the bit is erased when the 
button is pressed. The N flag works that way with the TST command as 
well. The BPL command in the program above branches if the button was 
pressed. The PL stands for plus and it is set when the sign bit is cleared. 

Here is the complete program to check the fire button and joystick 
difference: 

;(5.3C) fire button & joy difference 



;Test subroutine 
;Was fire button 2 hit? 
;Yes ! Branch 
Jcontinute until broken 



test: 








jsr 


run 




tst.b 


$bfe001 




bpl 


fire 




jmp 


test 


joy = 


$dff00a 




run: 
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;01d position in D6 
;New position in D7 
;Dif ference in D6 
;rts for Seka and other 

fire: 

nop ;Breakpoint here 



end 



move 


d7,dS 


move 


joy,d7 


sub 


d7,d6 


jmp 


run 
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5.4 Tone production 



It's fun to make noises and sounds. The Amiga let's you use Audio 
Devices and various I\0 structures to play tones, noises and/or music 
pieces in the background. You'll leave this method to C or BASIC pro- 
grammers, since you can use short machine language programs to directly 
program the audio hardware. 

The Paula chip has all the capabilities needed for tone production. This 
chip can be accessed using the hardware registers of the processor. No 
library of any high level language can do more than you can — program 
the chip. 

How does it work? Since the disk uses Direct Memory Access (DMA) to 
get information, you just need to tell it where to look for the tone or tone 
sequences that you would like played. You also need to tell it how to 
interpret the data. 

Let's start with the easiest case — producing a constant tone. A tone like 
this consists of a single oscillation that is repeated over and over. If you 
make a diagram of the oscillation, you see the wave form of the oscilla- 
tion. There are several standard waves: sine, square, triangle and saw 
tooth. The simplest is the square wave. 

To produce a square wave, you just need to turn the loud speaker on and 
off. The frequency that occurs here is the frequency of the tone. 

You want to produce such a tone using the Amiga. First you need to 
make a table that contains the amplitude of the tone you wish to produce. 
For a square wave, you only need two entries in the table, a large and a 
small value. Since the sound chip in the Amiga has amplitude values 
between -128 and +127, our table looks like this: 

soundtab: 

dc.b -100,100 

You need to give the address of the table to the sound chip. You have four 
choices, since the Amiga has four sound channels. The address of the 
hardware register in which the table address for channel must be written 
is $DFFOA0; for channel 1 it is $DFF0B0; for channel 2 it's $DFF0C0; 
for channel 3 it's $DFF0D0. For stereo output, channels and 3 control 
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the left loud speaker. Channels 1 and 2 control the right loud speaker. For 
example, choose channel and write the following: 

move.l #soundtab,$DFF0A0 JAddress of the table 

Next, you need to tell the sound chip how many items there are in the 
table. The data is read from beginning to end and sent to the loud speaker. 
Once it reaches the end, it starts over at the beginning. Since the sound 
chip gets this one word at a time, even though the data is in bytes, the 
table must always have an even number of bytes. The length that you 
give it is the number of words, the number of bytes/2. 

You put the length for channel in the register at address $DFF0A4 (for 
channel x just add x*$10!): 

move #l,$df f0a4 jLength of table in words 

Now you have to tell it how quickly to read the data and output it to the 
loud speaker. This word determines the frequency. However, it does this 
"backwards". The larger the value, the lower the frequency. Choose the 
value 600 for this example: 

move #600, $df f 0a6 ;Read in rate 

Now you need to decide the loudness level for the tone or noise. You have 
65 different levels to choose from. Let's choose the middle level value 40 
for our example. 

move #40,$df f0a8 loudness level 

That's the data that the sound chip needs to produce the tone. However, 
nothing happens yet. What next? The chip can't tell if the data that's in 
the registers is valid, so it doesn't know if it should use the data. 

You need to work with the DMA control register at address $DFF096 to 
let it know. You only need six bits of this word for your purposes: 

Bit 15 ($8000) If this bit is set, every bit that is written to this internal 
register is set. Otherwise the bits are erased. Zero bits 
aren't affected. This is very useful because this word 
also contains DMA information for disk operations that 
shouldn't be changed. 

Bit 9 ($200) This bit makes it possible for the chip to access DMA 
memory. If you want to start playing the tone, you 
need to set this bit 

Bits 0-3 Turn channel 0-3 on when the bits are set. 

You'll start your tone by setting bits 15, 9 and 0: 
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move #$8000 + $200 + l,$df f 096 jStart DMA 

Here's an example of tone production — this time with a tone using a sine 
wave: 



;** Sound generation using hardware registers ** (5.5A) 

ctlw = $dff096 

cOthi = $df fOaO 

cOtlo = cOthi + 2 

cOtl = c0thi + 4 

cOper = cOthi+6 

cOvol = cOthi+8 

run: 



move.l 

move 

move 

move 

move 

rts 



#table,cOthi 

#8,c0tl 

#400,c0per 

#40,c0vol 

#$8201,ctlw 



JDMA Control 
;Table address HI 
;Table address LO 
jTable length 
;Read in Rate 
JLoudness level 
;* Produce a simple tone 
;Table beginning 
jTable length — 8 words 
;Read in rate 
;Loudness level (Volume) 
;DMA/Start Sound 



data 
table: 
deb -40,-70,-40,0,40,70,40,0 



;>500K place in CHIP memory 
;Sound table: sine 



end 

To test this subroutine, use AssemPro to assemble the routine, save the 
program and load it into the debugger. Next set a breakpoint at the RTS, 
to set the breakpoint in AssemPro select the correct address with the 
mouse and press the right- Amiga-B keys. Start the program and listen to 
the tone. You need another routine to turn the tone off, turn your sound 
down for now. 

To turn the tone off, you just need to erase bit of the DMA control 
register. To do this, you just need to write a in bit 15 and all the set 
bits in this register are erased. To erase bit 0, just write a one to the 
memory location: bit 15=0 => bit is erased. Here's a small routine to 
stop the tone coming from channel 0: 



still: 



move 
rts 



#l,ctlw 



;* Turn off tone 
jTurn off channel 1 



Now let's use the routine in a program to produce a short peep tone, that 
you could, for instance, use as a key click: 



;** Producing a peep tone ** 

ctlw =$dff096 

cOthi = $dff0a0 

cOtlo = cOthi + 2 

cOtl = c0thi+4 

cOper = c0thi+6 



JDMA Control 
;HI table address 
;LO table address 
;Table length 
JRead in rate 
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cOvol = cOthi+8 
beep: 



JVolume 

;* Produce a short peep tone 
move.l #table,cOthi JTable beginning 





move #8,c0tl 


JTable length 




move #400,c0per 


;Read in rate 




move #65,c0vol 


;Volume 




move #$8201,ctlw 


jStart DMA (Sound) 




move.l #20000,d0 


jDelay counter 


loop: 








dbra dO,loop 


;Count down 


still: 








move #l,ctlw 


jTurn off tone 




rts 




table: 




JSound table 




dc.b 40,70,90,100,90,70, 


,40,0,-4,0 




end 





You can play up to four tones at the same time in such a way that they 
are independent of each other. The Amiga also offers another method of 
making the sound more interesting: you can modulate the tone. 

Let's produce a siren tone. You could do this by figuring out the entire 
sequence and programming it. However, as you can well imagine, that's a 
lot of work. 

It's much easier to use two tone channels. Let's use channel 1 for the 
base tone and channel for its modulation. Channel needs to hold the 
envelope of the siren tone. It needs to give the expanding and contracting 
of the tone at the right speed. 

You then have two ways that you can have channel zero work with 
channel one. You can control the volume via channel 0, the read in rate 
(frequency), or both. For our example, you'll use the frequency modula- 
tion. 

Change the program as follows: 

;** Modulated sound generation via hardware registers ** 

ctlw = $df f096 JDMA Control 

adcon = $df f 09e jAudio/Disk Control 

cOthi =*$df f OaO ;HI table address 

cOtlo = cOthi + 2 ;LO table address 

cOtl = c0thi + 4 JTable length 

cOper = cOthi + 6 jRead in rate 

cOthi + 8 JVolume 



cOvol 
run: 



move.l #table,c0thi + 16;Table start for channel 1 

move #8,c0tl + 16 JTable length — 8 words 

move #300,c0per + 16 ;Read in rate 

move #40,c0vol+16 JVolume 

move.l #table2,c0thi JTable start for channel 
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still: 



table: 



move 
move 
move 

move 
move 
rts 

move 
move 
rts 



#8,c0tl ;Table length 

#60000, cOper ;Read in rate 

#30,c0vol ;Volume 

#$8010,adcon ;Modulation mode: FN 

#$8203,Ctlw jStart DMA 



#$10,adcon 
#3,ctlw 



* Turn off tone 

No more modulations 

Turn off channels 



;Data for basic tone 
dc.b -40,-70,-90,-100,-90,-70,-40,0 
dc.b 40,70,90,100,90,70,40,0 

table2: ;Data for Modulation 

dew 4 0,430,470,500,530,500,470,430 



end 

When you start the program, you'll hear a siren. You can change this 
tone to your heart's content. 

Did you notice the added "adcon" register. This register controls the 
modulation of the audio channel as well as handling disk functions. The 
same technique is used here as for the DMA control register, bits can only 
be set if bit 15 is. As a result, you don't have to worry about the disk 
bits. I'd recommend against experimentation. 

Control bit 15 isn't the only one of interest to you. You can also use bits 
0-7, because they determine which audio channel modulates another 
channel. There is a restriction, though. A channel can only modulate the 
next higher numbered channel. For this reason, you use channel 1 for the 
basic tone and channel for the modulation in the example. You can't, 
for example, modulate channel three with channel zero. Channel 3 can't 
be used to modulate any other channel. 

Here is an overview of bits 0-7 of the "adcon" register. 



Bit 



Function 



Channel modulates the 

1 Channel 1 modulates the 

2 Channel 2 modulates the 

3 Turn of channel 3 

4 Channel modulates the 

5 Channel 1 modulates the 

6 Channel 2 modulates the 

7 Turn off channel 3 



volume of channel 1 
volume of channel 2 
volume of channel 3 

frequency of channel 1 
frequency of channel 2 
frequency of channel 3 
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In the example, you set bit 4, which put channel in charge of channel 
one's frequency modulations. 

When you've chosen a channel for use in modulating another channel, 
some of the parameters of the channel change. You don't need to give 
volume for this channel, so you can omit it. Now the table's data is 
looked at as words instead of as bytes. These words are read into the 
register of the modulated register at a predetermined rate. The Read in Rate 
Register determines the rate. 

If you want to modulate the frequency and the volume of another channel 
(In the example, set bits and 4 of "adcon"), the data is interpreted a little 
differently. The first word in the table is the volume, the second is the 
read in rate, and so on. It alternates back and forth. In this way, you can, 
for instance, produce the siren tone. 
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5.5 Hardware registers overview 



The following tables should give you an overview of the most important 
hardware registers. There's not enough room to describe each register, so 
I'd recommend getting a hold of the appropriate technical literature. If you 
experiment with these registers, you should keep in mind that this can 
cause the computer to crash. Save your data to disk and then take the disk 
out of the drive, because you might cause the disk drive to execute some 
wierd functions. 

Let's start with the PIAs. This covers the PIA type 8520. You should 
keep in mind that some functons and connection of the 8520 are inte- 
grated into the Amiga and so there are limitations on what you can do 
with the PIAs. 

PIA A PIAB Register's Meaning 

Data register A 

Data register B 

Data direction register A 

Data direction register B 

Timer A LO 

Timer A HI 

Timer B LO 

Timer B HI 

Event register Bits 0-7 

Event register Bits 8-15 

Event register Bits 16-23 

Unused 

Serial data register 

Interrupt control register 

Control register A 

Control register B 

Some internal meanings: 

$BFE 101 Data register for the parallel interface 

$BFE301 Data direction register for the parallel interface 

$BFEC01 State of the keyboard, contains the last special key 

pressed (Shift, Alternate, Control, Amiga) 



BFE001 


BFE000 


BFE101 


BFE100 


BFE201 


BFE200 


BFE301 


BFE300 


BFE401 


BFE400 


BFE501 


BFE500 


BFE601 


BFE600 


BFE701 


BFE700 


BFE801 


BFE800 


BFE901 


BFE900 


BFEA01 


BFEA00 


BFEB01 


BFEBOO 


BFEC01 


BFECOO 


BFED01 


BFEDOO 


BFEE01 


BFEEOO 


BFEF01 


BFEFOO 
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Now come the registers that are used for tone production. The first two 
registers should be treated especially carefully — if they are used wrong, 
very nasty effects can occur. 

These registers can be either read or written only. This information is 
included under R/W in the table. 



Address 



R/W Meaning 



DFF096 


W 


Write DMA Control 


DFF002 


R 


Read DMA Control and Blitter Status 


— Audio channel - 




DFFOAA 


W 


Data register 


DFFOAO 


W 


Pointer to table beginning Bits 16-18 


DFF0A2 


W 


Pointer to table beginning Bits 0-15 


DFF0A4 


W 


Table length 


DFF0A6 


W 


Read in Rate / Period 


DFF0A8 


W 


Volume 


- Audio channel 1 - 




DFFOBA 


W 


Data register 


DFFOBO 


W 


Pointer to table beginning Bits 16-18 


DFF0B2 


W 


Pointer to table beginning Bits 0-15 


DFF0B4 


W 


Table length 


DFF0B6 


w 


Read in Rate / Period 


DFF0B8 


w 


Volume 


- Audio channel 2 -- 




DFFOCA 


w 


Data register 


DFFOCO 


w 


Pointer to table beginning Bits 16-18 


DFF0C2 


w 


Pointer to table beginning Bits 0-15 


DFF0C4 


w 


Table length 


DFF0C6 


w 


Read in Rate / Period 


DFF0C8 


w 


Volume 


-- Audio channel 3 -- 




DFFODA 


w 


Data register 


DFFODO 


w 


Pointer to table beginning Bits 16-18 


DFF0D2 


w 


Pointer to table beginning Bits 0-15 


DFF0D4 


w 


Table length 


DFF0D6 


w 


Read in Rate / Period 


DFF0D8 


w 


Volume 
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Now for the registers that contain information about the joystick, mouse 
or potentiometer. These addresses have been gone over in part previously. 



Address R/W Meaning 



DFFOOA R Joystick/Mouse Port 1 

DFFOOC R Joystick/MousePort 2 

DFF012 R Potentiometer pair 1 Counter 

DFF014 R Potentiometer pair 2 Counter 

DFFO 18 R Potentiometer connection 

DFF034 W Potentiometer port direction 
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6 The Operating System 



Now let's take a step forward in your ability to write assembly language 
programs. It's not enough to put a piece of text in memory someplace. 
You want to be able to put it on the screen. Do you know how to write a 
character on the screen? Do you know how to draw a window on the 
screen that can be modified by the mouse? Actually, you don't have to 
have terribly precise knowledge about such topics. 

Fortunately, the Amiga's operating system supplies routines that take 
care of common tasks like this. It can seem quite complicated due to the 
number of routines necessary. These routines are in libraries. We'll look 
at the libraries in some depth now. 



6.1 Load libraries 



Before you can use a library, it must be available. It has to be loaded into 
memory. Unfortunately, the whole library must be loaded, even if you 
only need one of the functions. 

First you need to decide what the program must be able to do, so you can 
see which libraries you'll need. For simple I/O text, you don't need a 
library that contains routines for moving graphics! 

There are a number of libraries on a normal Workbench disk. Here's an 
overview of the names and the sort of functions they contain: 

exec.library This library is needed to load the other libraries. It is already in memory 

and doesn't need to be loaded. It's in charge of basic functions like reserv- 
ing memory and working with I/O channels. 

dos. library Contains all the functions for normal I/O operations, for instance screen 

or disk access. 

intuition.library Used for working with screens, windows, menus, etc... 

clist.library This contains routines for working with the Copper lists that are used for 

controlling the screen. 
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console. library Contains graphics routines for text output in console windows. 

diskfont. library Used for working with the character fonts that are stored on the disk. 

graphics. library This library contains functions to control the Blitter (or graphics) chip. 
It's used for basic graphics functions. 

icon.library Used in the development and use of Workbench symbols (icons). 

layers. library Used for working with screen memory (layers). 

mathffp. library Contains basic math floating point operations. 

mathieeedoubbas. library 

Contains basic math functions for integers. 

mathtrans. library 

Contains higher level mathematical functions. 

potgo.library Used for evaluating analog input to the Amiga. 

timer. library Contains routines for time critical programs. They can be used to pro- 
gram exact time intervals. 

translator. library Contains the single function "Translate", that translates normal text writ- 
ten phonetically for the narrator, the speech synthesizer. 

You can open (load) all these libraries of course. You should remember 
that this takes time and memory. For this reason, you should always 
think about which functions you need and which libraries they are in. 

For example, let's say you want to write a program that does text input 
/output. You need the "dos.library", so it can be loaded. 

The "exec. library" is in charge of loading. This library contains the Open- 
Lib function that can be called once you've passed the needed parameters. 
AssemPro Amiga includes all of the libraries necessary for the Amiga, it 
also includes files that contain the offsets for the operating system calls. 
The macros contained in AssemPro ease assembly language programming 
considerably. To make the programs in this book useful to the largest 
audience the following examples are written for generic assemblers and do 
not include AssemPro's macros. We have used the AssemPro ILABEL 
and the macros INITAMIGA and EXITAMIGA so AssemPro owners 
can start the programs from the desktop. If you are using a different 
assembler check your documentation for instructions on linking 
programs.) 
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6.2 Calling functions 



Since this chapter is rather complex we'll first describe the fundamental 
routines necessary to use the Amiga's operating system, after a decsrip- 
tion a complete program is listed. Every library begins in memory with a 
number of JMP commands. These JMPs branch to the routines that are in 
the library. To call a function, you need to find the beginning of this 
JMP table and call function x by going to the xth JMP command. 
Usually you use an offset to get to the right JMP command. Normally, 
you don't start at the beginning but at the end of the JMP table, so use 
negative offsets. 

It works out very easily. Now let's open the "dos.library" by using 
"exec.library's" base address. This address is $000004. To call a function 
from another library, you need to use another base address. 

Now you need the offset for the function that you want. You want the 
OpenLib function that has -408 as an offset. You'll find a list of func- 
tion offsets in the appendix. 

You need a pointer to the name of the library you are loading for the 
OpenLib function (in this case "dos.library") and a long word in memory 
that you can use to store the base address of the DOS library. You get 
this back from the OpenLib function. You need to be sure to write the 
library name in lowercase letters (dos.library), otherwise you can't open 
it. I entered a name in capital letters once and spent a lot of time finding 
this error. 

The routine looks like this: 

;** Load the DOS library 'dos.library' (6.2A) ** 
ExecBase = 4 ;Base address of the EXEC 

;library 
OpenLib =-408 ;Off set from the OpenLib 

;f unction 

IoErr = -132 ;Of fset for IoErr information 

init: 



move.l 


ExecBase, a6 


;Base address in A6 


lea 


dosname,al 


;Address of library name 


moveq 


#0,d0 


;Version number 


jsr 


OpenLib (a6) 


;Open DOS library 


move.l 


d0,dosbase 


;Save DOS base address 
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beq error ;If zero, then error ! 

;Your program goes here 
;More program... 



;Error 
move.l dosbase, a6 ;Address of library name 
jsr IoErr(a6) ;Call IoErr for error info 



move.l d0,d5 
rts 



;Your error routine goes here 



dosname: ;Name of the library to opened 

dc.b 'dos. library ',0,0 

align ;Seka uses - even 

dosbase: ;Storage for DOS base address 

blk.l 1 

end 

This is the way to load the DOS library so that you can use it. All library 
functions are called in this way. Parameters are put in registers and passed 
to the function. When there is an error, when the function doesn't run 
correctly, a zero is usually put in data register DO 

Once your program is done with its work, you need to close the libraries 
that are still open before you return to the CLI or Workbench. The 
CloseLib function (offset -414) takes care of this job. This function is in 
the EXEC library just like OpenLib. The only parameter it needs is the 
base address of the library that is closed. To close "dos.library", do the 
following: 

CloseLib = -414, ;(6.2B) 

move.l ExecBase,a6 ;EXEC base address 
move.l dosbase, al ;DOS base address 
jsr CloseLib(a6) ;Close library 
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6.3 Program initialization 



Before you can start a program, you need to initialize many things so that 
the program can run. 

Let's take an example program that does some text editing. A program 
like this must be able to store text, so it needs to be able to access mem- 
ory. It also needs to be able to accept keyboard input and to do screen 
output, so it needs an output window. 

To do this, you need to open one or more of the libraries that we talked 
about earlier. Let's assume that you've loaded the DOS library, so that 
you can do the next steps. 



6.3.1 Reserve memory 

There are several ways to get the operating system to assign you a chunk 
of memory. You need to use one of them, so that during multitasking, 
you don't have one program overwritting another programs memory area. 

Let's look at the function that is normally used. This function is in the 
resident EXEC library and has the name AllocMem (offset -$c6). It 
reserves a memory area, using the value in DO as the length. The address 
that the memory area begins at is returned in the DO data register. If it 
returns zero, the program couldn't give you that much memory. 

You can also use a mode word in Dl to determine whether the memory 
area that is reserved should be erased or not. 

The routine looks like this: 



xecBase = 4 




;(6.3.1A) 


llocMem = -$c 


6 




move.l 


#number,dO 


;Number of bytes to reserve 


move 


#mode,a6 


;Mode word 


move.l 


ExecBase,a6 


;DOS base address in A6 


jsr 


AllocMem (a6) 


;Call function 


move.l 


dO, address 


;Save memory ' s start address 


beq 


error 


jMemory not reserved 
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The second way to reserve memory is to use the AllocAbs function (off- 
set -$CC). This function in confrast to the AllocMem function reserves a 
particular memory area. The DO register contains the number of bytes that 
should be reserved. Address register Al contains the desired start address. 
This function returns a zero in DO if the memory area can't be reserved. 



ExecBase = 4 




;(6.3.1b) 


AllocAbs = -$cc 




move.l 


#number,dO 


JNumber of bytes to reserve 


lea 


address, al 


;Desired start address 


move.l 


execbase,a6 


JEXEC base address 


jsr 


AllocAbs (a6) 


;Reserve memory 


tst.l 


dO 


jEverything OK? 


beq 


error 


;No! 



When the program has done its work and must return to the CL I or the 
Workbench, it needs to return the memory it has reserved to the system. 
The FreeMem function (offset -$D2) handles this. 

This function works like AllocAbs in that the number of bytes is put in 
DO and the start address of the memory area is put in A 1. If you try to 
free up a memory area that wasn't reserved, you usually crash the compu- 
ter. 

The routine to free up a memory area looks like this: 



ExecBase = 4 




;(6.3.1C) 


FreeMem = -$d2 




move.l 


#number,dO 


JNumber of bytes released 


lea 


address, al 


;Start address from AllocAbs 


move.l 


ExecBase, a6 


;EXEC base address 


jsr 


FreeMem (a6) 


JFree up memory 


tst.l 


dO 


Everything OK ? 


beq 


error 


;No ! 



6.3.2 Opening a simple window 

The title of this chapter may sound a bit strange. However, the differences 
between the two different methods of opening a window are so great that 
they should be handled in separate chapters. 
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The method of opening a window presented here is very simple, but it 
doesn't allow you to work with all of the gadgets. These gadgets include 
the close symbol in the upper left corner of a window and the size symbol 
in the lower left corner. 

If you open the window in the simple manner, almost all the gadgets are 
present. However, the close symbol is not. As a result, this method isn't 
appropriate for every application. Now let's look at the method. 

To open a window, use a function from the DOS library, so you need to 
open the library first (see the section "Load library"). This open function 
is an all purpose function that can be used for many things. For this 
reason, it makes good sense to put a "open" subroutine in your program. 
You can use it a lot. Let's do the basic steps: 



;** Load the DOS library ' dos. library ' (6.3.2A)** 
ExecBase = 4 ;Base address of the EXEC 

library 
OpenLib =-408 ;Of f set of OpenLib function 

;Of fset of the DOS function OPEN 



|Base address in A6 
;Address of library name 
jVersion number: unimportant 
;Call the function 
;Save DOS base address 
;if zero, then error ! 
jMore of your program 
;Now open window, etc... 



Open 


= -30 




init: 








move.l 


ExecBase, a6 




lea 


dosname (pc) 




moveq 


#0,d0 




jsr 


OpenLib (a6) 




move.l 


d0,dosbase 




beq 


error 



;Error occured 
;Your error routine 



Openf ile: 

move.l dosbase,a6 
jsr Open (a6) 
tst.l dO 
rts 



JGeneral OPEN function 
;DOS base address in A6 
;Call OPEN function 
;Test if OK 
JDone, evaluate test later 



dosname: ;Name of library to be opened 

dc.b 'dos. library ' ,0,0 

align Jeven 

dosbase: JSpot for DOS base address 

blk.l 1 
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You called the Openfile routine, because the label "Open" is already being 
used for the offset. This routine calls the Open function that is in the 
DOS library. 

That isn't everything. The function must be given some parameters so 
that it knows what to open. The parameters are sent in registers Dl and 
D2. Dl points to a definition block that specifies what should be opened. 
You need to have a filename ended with a null byte there. Dl must be 
passed as a long word like all addresses. D2 contains the mode that the 
function should run in. There is an old (1005) and a new (1006) mode. 
This number must be passed in D2's long word. 

Here's an overview of how windows are opened. Fortunately, AmigaDOS 
allows you to use input and and output channels in the same way. The 
standard channels are disk files, the console (keyboard and screen), the 
printer interface and the serial RS232 interface. 

The console input/output is what you'll work with now. When you spec- 
ify the console as the filename of the channel to be opened, a window is 
opened automatically. 

The name must begin with CON: to do this. It's similar to DFO: for disk 
operations. A little more information about the window is still needed. 

You need to specify the X and Y coordinates of the upper left and lower 
right corners of the window as well as the name that should appear in the 
title line of the window. A complete definition block for a window like 
this would appear like the following line: 

consolname*. dc.b 'CON:0/100/640/100/** Window ** ',0 

To open this window, the line above needs to be inserted in the following 
program: 

mode__old = 1005 

lea consolname (pc) ,al JConsole Definition 

move.l #mode_old,d0 Jmode 

bsr openfile JConsole open 

beq error Jdidn't work 

move.l d0,conhandle 

rt s 

conhandle: del 1 jSpace for handle 

There are two points to clear up yet. 
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You should use modeold as the mode when you open a window. Logi- 
cally the window doesn't exist before opening so this seems weird but it 
doesn't hurt anything. 

The parameter that returns from "openfile" in DO is zero in the case of an 
error, in the case that opening didn't work. Otherwise the value is the 
identification number (handle number) of the opened channel. You need to 
store it away, because every function that wants to use this channel must 
give the handle number. In the example, you stored this number in the 
"conhandle" long word. 

As mentioned, the window you've opened doesn't have a close symbol, 
but it can be made bigger and smaller and moved forward and back. The 
manipulations that are carried out using the mouse are completely taken 
care of by the Amiga (in contrast to the ATARI ST where the program- 
mer has to take care of these things). 

An important function that uses the handle number is the one that closes 
the channel (in your case the window). This function is also in the DOS 
library and is called "Close". Its offset is -36 and it only needs one para- 
meter; the handle number of the channel that is closed must be in the Dl 
register. 

After your work is done, you need to put the following lines in your 
program to close the window: 

Close = -36 ;(6.3.2C) 

move.l conhandle,dl ;Handle number in Dl 
move.l dosbase,a6 ;DOS base address in A6 
jsr Close (a6) ;Close channel! 

The window disappears! 

Now for a few remarks about opening and closing the window in this 
way. If you open several windows in the same way, you'll get several 
windows and thus several handle numbers. In this way, you can put as 
many windows on the screen as you'd like. You can do your work with 
them and then close them indivudally. 

Here is the complete program to open and close a simple window in 
AssemPro format (We have used the AssemPro ILABEL and the macros 
INITAMIGA and EXITAMIGA so AssemPro owners can start the 
programs from the desktop. If you are using a different assembler check 
your documentation for instructions on starting and exiting programs.): 
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;***** 6.3.2 S.D. ***** 



OpenLib 

closelib 

;ExecBase 



=-30-378 

=-414 
=4 



calls to Amiga Dos: 



Open 


=-30 


Close 


=-30-6 


IoErr 


=-132 


mode old 


= 1005 


alloc abs 


=-$cc 



ILABEL Assempro:includes/Amiga.l 
INIT AMIGA 



run: 



test: 



bsr 
bra 



mit 
test 



move.l ExecBase,a6 

lea dosname (pc) ,al 

moveq #0,d0 

jsr openlib(a6) 

move.l d0,dosbase 

beq error 

lea consolname (pc) ,al 

move.l #mode_old,d0 

bsr openfile 

beq error 

move.l d0,conhandle 

rts 



bra qu 



; Defined in AssemPro 
Macros 



;AssemPro only 
;AssemPro only 



initialization 
;System-Test 

;System initialization 
and open 

;Number of Execute- 
library 



;Open DOS-Library 

;Console Definition 
;Console open 



;quit and exit 



qu: 



move.l dosbase,a6 

jsr IoErr(a6) 

move.l d0,d5 

move.l #-l,d7 

move.l conhandle,dl 

move.l dosbase,a6 

jsr close(a6) 



;Flag 
;Window close 



no 
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move.l dosbase,al jDOS.Lib close 

move.l ExecBase,a6 



jsr closelib(a6) 

EXIT_AMIGA JAssemPro only 



openf ile: ;Open File 

move.l al,dl jPointer to 1/0- 



De fin it ion-Text 



move.l d0,d2 

move.l dosbase,a6 

jsr open(a6) 

tst.l dO 
rts 



dosname: dc.b ' dos. library ' ,0,0 

Align.w 
dosbase: del 
consolname: dc.b 'CON:0/100/640/100/** CLI-Test ** ',0 

Align.w 
conhandle: del 

end 

There is another way to open a window easily. Just use RAW: instead of 
CON: as the channel designator. All the other parameters and operations 
remain the same. 

If you try them both out, you won't see any differences between the two 
windows. They both look the same and can be worked with in the same 
way with the mouse. The difference comes when you input to the win- 
dow. In the RAW: window, the cursor keys are ignored. In the CON : 
window and in CLI, they do work. 
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6.4 Input/Output 



Besides managing and making calculations with data, the most important 
work of a program is to input and output the data. There are many meth- 
ods of data transfer in and out of the computer, for instance screen or 
printer output, keyboard input, using the serial or the parallel interface, 
tone or speech output and finally disk operations. 

You want to learn about all these methods of data input and output for 
programming and applications. We've written some programs as subrou- 
tines that should be useful for later programs. It makes good sense to 
make a library of these subroutines that can either be directly integrated in 
a new program or linked to a program. At the end of the sections there is 
a list of a complete program so you can see how the subroutines are used. 

To prepare for input/output, you need to have data to output and space to 
input data. To get this ready, you need a correct program beginning in 
which the EXEC and DOS libraries are opened and memory is reserved. 
After this, you begin most programs by outputing some text. The text 
can be a program title or the instruction to input data over the keyboard. 
Let's start looking at screen output. 



6.4.1 Screen output 



For a computer like the Amiga the first question is where should the 
screen output be sent? The answer is simple for many computers; they 
only have one screen, and output goes there. You need to specify which 
window to write to when you use the Amiga, however. 

There are two possibilities: 

1. Output to the CLI window 

2. Output to another window 

The first possibility only exists if the program that makes the output was 
started from CLI. If not, you need to open your own custom window for 
your program. If so, you can use the window that was opened by the CLI 
for output. 



112 



Abacus 6. Amiga Operating System 



If you use the second method, you need to open a window. As you've al- 
ready seen, there are three methods. For simple text and character output, 
the difference between the three sorts of windows isn't very great. Here 
you have a free hand in determining which sort of window to use. Let's 
open a CON : window and put its handle number in "conhandle". 

You've opened your window and want to output a tide. You choose text 
to output and then put it in memory using a code segment like this: 

title: dc.b "** Welcome to this program ! **" 

titleend: 

align ; even 

The "align" (even) is a pseudo-op that should follow text when it is fol- 
lowed by either word data or program lines. It causes the assembler to 
insert a null byte if necessary to make the next address even. 

To output this text you need another DOS function: Write. This has an 
offset of -48 and needs three parameters: 

In Dl the handle of an opened output channel that should be written to 
(in your case, this is the handle number that you got back from 
the Open command when you opened your window.). 

In D2 the address of the text to be output (in the example, the address 
"title"). 

In D3 the number of characters to be output in bytes. 

To find the number of bytes to output, you need to count the number of 
characters in your text. Use "titleend" to calculate this. Using this label, 
the assembler can calculate the length of your text for itself (after all, why 
should you count when you have a computer?) if you write: 

move.l #titleend-title,d3 

The advantage of specifying the length is that you can put control char- 
acters between the beginning and end of the text. In this way, you can 
execute certain functions using text output. You'll learn about the control 
characters in a bit. 

Here's the routine: 

Write = -48 ;(6.4.1A) 

;Open window 

move.l dosbase,a6 ;DOS base address 

move.l conhandle, dl ;Pass handle 

move.l #title,d2 ;Text address 

move.l #titleend-title,d3 ;And length 

jsr Write (a6) ;Call function 
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title: dc.b 

titleend: 

align 

end 



'** Welcome to this program ! **' 

Jevent 



pmsg 
pline 

pchar 
pcrlf 



You'll certainly use this function a lot. You'll often want to output just 
one character though. To allow you to do this and similar text related 
tasks, there are four subroutines, each of which do a different sort of out- 
put: 

Outputs the text from (D2) to the first null byte. 

Is the same as the routine above except that the text is automatically fol- 
lowed by a CR, the cursor is positioned at the beginning of the next line. 

Outputs the character in DO. 

Puts the cursor at the beginning of the next line. 

Here's the subroutine package: 



Write : 



-48 



(6. 4. IB 



pline: 








bsr 


pmsg 


pcrlf. 








move 


#10, dO 




bsr 


pchar 




move 


#13,d0 


pchar: 








move.b 


dO, outline 




move.l 


#outline,d2 


pmsg: 








move.l 


d2,a0 




clr 


d3 


ploop: 








tst.b 


(a0) + 




beq 


pmsg2 




addq.l 


#l,d3 




bra 


ploop 


pmsg2: 








move.l 


dosbase,a6 




move.l 


conhandle,dl 




jsr 


Write (a6) 




rts 




outline: 


dew 


conhan 


die: 


del 



Output line and then a CR 
;Output line 

* Move cursor to the next line 
Line feed 

[Output 
;and CR 

* Output character in DO 
[Character in output buffer 
;Address of the character 
*Output line (D2) up to null 

[Address in A0 
Length = 

Null byte ? 

Yes: length found 

Else Length+1 

And continue looking 

1DOS base address in A6 

[Our window handle 

[Call Write function 

[Done ! 

[Output buffer for 'pchar ' 

[Window ' s handle 
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Here is an example program to open and close a simple window and out- 
put a text message in AssemPro format (We have used the AssemPro 
macros INITAMIGA and EXITAMIGA so AssemPro owners can start 
the program from the desktop. If you are using a different assembler check 
your documentation for instructions on starting and exiting programs.): 

Here is the complete program in AssemPro format: 

; ***** 6.4.1C.asm S.D. ***** 



OpenLib =-30-378 

closelib =-414 
jExecBase =4 



; Defined in AssemPro 
; Macros 



calls to Amiga Dos: 



Open 




=-30 


Close 




=-30-6 


Write 




=-48 


IoErr 




=-132 


mode old 


= 1005 


alloc 


abs 


=-$cc 



ILABEL AssemProlincludes/Amiga.l /AssemPro only 



test: 



INIT_AMIGA 


bsr 


init 


bsr 


test 


nop 




bra qu 




move.l 


#title,d0 


bsr 


pmsg 


bsr 


pcrlf 


bsr 


pcrlf 



jAssemPro only 



;initialization 
;System-Test 

;quit and exit 



rts 



init: 



move.l ExecBase,a6 

lea dosname (pc) ,al 

moveq #0,d0 

jsr openlib(a6) 

move.l d0,dosbase 

beq error 



;System initialization 
and open 

;Number of Execute- 
library 



;Open DOS-Library 
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lea consolname (pc) ,al jConsole Definition 

move.l #mode_old,dO 

bsr openf ile jConsole open 

beq error 

move.l dO,conhandle 



rts 



pmsg: JPrint message (dO) 

movem.l d0-d7/a0-a6,- (sp) 
move.l dO,aO 



ploop: 



pmsg2: 



move.l a0,d2 

clr.l d3 

tst.b (a0) + 

beq pmsg2 

addq.l #l,d3 

bra ploop Jlength calculate 

move.l conhandle,dl 

move.l dosbase,a6 

jsr write(a6) 

movem.l ( sp) +,d0-d7/a0-a6 

rts 

per if: 

move #10,d0 

bsr pchar 

move #13, dO 
pchar: Joutput char in D) 

movem.l d0-d7/a0-a6,- (sp) Jsave all 

move.l conhandle,dl 



pchl: 



error: 



qu: 



lea outline, al 

move.b dO,(al) 

move.l al,d2 

move.l #l,d3 ;l letter 

move.l dosbase,a6 

jsr write(a6) 

movem.l (sp) + f d0-d7/a0-a6 Jrestore all 

rts 



move.l dosbase,a6 

jsr IoErr(a6) 

move.l d0,d5 

move.l #-l,d7 ;Flag 

move.l conhandle,dl ;Window close 

move.l dosbase,a6 

jsr close(a6) 

move.l dosbase,al jDOS.Lib close 
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move.l ExecBase,a6 
jsr closelib(a6) 

EXIT_AMIGA ;AssemPro only 

openf ile: ;Open File 

move.l al,dl jPointer to 1/0- 



De fin it ion -Text 



move.l d0,d2 

move.l dosbase,a6 

jsr open (a6) 

tst.l dO 
rts 



dosname: dc.b ' dos. library ',0,0 

Align.w 
dosbase: del 
consolname: dc.b ' CON:0/100/64 0/100/** CLI-Test ** ',0 

Align.w 

conhandle: del 

title: dc.b ' ** Weclome to this program ! **' 

titleend: 

align 
outline: dew ;0utput buffer for pchar 

end 

Using this program, you can very easily put whatever you want in the 
CON : window. These functions also work in a RAW : window. You 
should rename "conhandle" as "rawhandle", so that you don't get things 
mixed up later. 

Let's stay with the CON: window. As mentioned earlier, you can output 
special characters that execute functions or change parameters for output. 
These characters are called control characters. 

You've already learned about one of these control characters, Line Feed 
($A). This character isn't just output; instead, it calls a function that 
moves the cursor into the next line and moves the screen up. This is very 
useful, but there are much more interesting control characters. 

Here's a list of control characters that execute functions. These characters 
are given in hex. 
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Control 


Sequence 


Function 


Sequence 


08 


Backspace 




0A 


Line Feed, Cursor down 




OB 


Move cursor up a line 




OC 


Clear screen 




0D 


Carriage Return, cursor in the first column 




OE 


Turn on normal characters (Cancels OF effects) 




OF 


Turn on special characters 




IB 


Escape 



The following sequences begin with $9B, the CSI (Control Sequence 
Introducer). The characters that follow execute a function. The values in 
square brackets can be left off. The n's you see represent one or more digit 
decimal numbers given using ASCII characters. The value that is used 
when n is left off, is given in the parenthesis that follow n in the 
description of the function in the table. 



Control 

Sequence 

Introducer 



Sequence 



Function 



9B [n] 40 Insert n blanks 

9B [n] 41 Move cursor n (1) lines up 

9B [n] 42 Move cursor n (1) lines down 

9B [n] 43 Move cursor n (1) characters to the right 

9B [n] 44 Move cursor n (1) characters to the left 

9B [n] 45 Move cursor down n (1) lines into column 1 

9B [n] 46 Move cursor up n (1) lines and into column 1 

9B [n] [3B n] 48 Cursor in line; Set column 

9B 4A Erase screen from the cursor 

9B 4B Erase line from the cursor 

9B 4C Insert line 

9B 4D Delete line 

9B [n] 50 Delete n characters starting at cursor 

9B [n] 53 Move up n lines 

9B [n] 54 Move down n lines 

9B 32 30 68 Line Feed => Line Feed + Return 

9B 32 30 6C Line Feed => just Line Feed 

9B 6E Sends the cursor position! A string of the 

following form is returned: 

9B (Line) 3B (Column) 52 
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Control Sequence Function 

Sequence 9B (Style) ;(Foreground color) ;(Background color) 6D 

Introducer The three parameters are decimal numbers in 

ASCII format. They mean: 

Style: = normal 
1 = bold 

3 = italic 

4 = underlined 
7 = inverse 

Foreground color: 30-37 

Color 0-7 for Text 

Background colon 40-47 

Color 0-7 for background 
9B (Length) 74 sets the maximum number of lines to be 

displayed 
9b (Width) 75 sets the maximum line length. 
9B (Distance) 78 defines the distance in pixels from the left 

border of the window to the place where output 

should begin 
9B (Distance) 79 defines the distance in pixels from the upper 

border of the window to the place where output 

should begin 

The last four functions yield the normal values 
if you leave off the parameters. 

9B 30 20 70 Make cursor invisible 
9B 20 70 Make cursor visible 

9B 71 Sends window construction A string of the 

following form is returned: 
9B 31 3B 31 3B (Lines) 3B (Columns) 73 

To see how the control characters work, have "pmsg" output this text to 
your window: 

mytext: dc.b $9b,"4;31;40m" ; (6. 3. 2D) 

dc.b "Underline" 
dc.b $9b,"3;3 3;4 0m",$9b, ,, 5;2 0H" 
dc.b "** Hello, World ! **",0 

The parameters for the control sequence are put in quotation marks so 
they are treated as an ASCII string. Now you see, just how easy it is to 
do text output! 

Here is the complete program to open and output the text and control 
codes to your window in AssemPro format (We have used the AssemPro 
macros INIT AMIGA and EXIT AMIGA so AssemPro owners can start 
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the programs from the desktop. If you are using a different assembler 
check your documentation for instructions on starting and exiting pro- 
grams): 

j***** 6. 4. ID. ASM S.D. ***** 

OpenLib =-30-378 

closelib =-414 

jExecBase =4 ; Defined in AssemPro 



Macros 



* calls to Amiga Dos: 



Open 




=-30 


Close 




=-30-6 


Write 




=-48 


IoErr 




=-132 


mode old 


= 1005 


alloc 


abs 


=-$cc 



ILABEL AssemPro:includes/Amiga.l ;AssemPro only 

;AssemPro only 



initialization 
;System-Test 



test: 



INIT_AMIGA 


bsr 


init 


bsr 


test 


nop 




bra qu 




move.l 


#mytext,d0 


bsr 


pmsg 


bsr 


pcrlf 


bsr 


pcrlf 



;quit and exit 



rts 



init: JSystem initialization 

and oprn 

move.l ExecBase,a6 ;Number of Execute- 

library 

lea dosname (pc) ,al 

moveq #0,d0 

jsr openlib(a6) ;Open DOS-Library 

move.l d0,dosbase 

beq error 

lea consolname (pc) ,al jConsole Definition 

move.l #mode_old,d0 

bsr openfile JConsole open 

beq error 

move.l d0,conhandle 
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rts 



pmsg: jPrint message (dO) 

movem.l d0-d7/a0-a6,- (sp) 
move.l dO,aO 
move.l a0,d2 
clr.l d3 



ploop: 



pmsg2: 



tst.b (a0) + 
beq pmsg2 
addq.l #l,d3 
bra ploop 

move.l conhandle,dl 

move.l dosbase,a6 

jsr write (a6) 

movem.l (sp) +,d0-d7/a0-a6 

rts 



pcrlf : 



pchar: ;output char in DO 

movem.l d0-d7/a0-a6,- (sp) Jsave all 
move.l conhandle,dl 



move 


#10,d0 


bsr 


pchar 


move 


#13,d0 



pchl: 



qu: 



lea outline, al 

move.b dO,(al) 

move.l al,d2 

move.l #l,d3 ;1 letter 

move.l dosbase,a6 

jsr write(a6) 

movem.l (sp) +,d0-d7/a0-a6 Jrestore all 

rts 



move.l dosbase,a6 

jsr IoErr (a6) 

move.l d0,d5 

move.l #-l,d7 JFlag 

move.l conhandle,dl ;Window close 

move.l dosbase,a6 

jsr close(a6) 

move.l dosbase,al ;DOS.Lib close 

move.l ExecBase,a6 jsr closelib(a6) 

EXIT AMIGA ;AssemPro only 
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openf ile: ;Open File 

move.l al,dl ;Pointer to 1/0- 



De fin it ion-Text 



move.l d0,d2 

move.l dosbase,a6 

jsr open(a6) 

tst.l dO 
rts 



dosname: dc.b ' dos. library ' ,0,0 

Align. w 
dosbase: del 
consolname: dc.b ' CON:0/100/640/100/** CLI-Test ** ',0 

Align.w 

conhandle: del 

mytext :dc.b $9b,' 4;31;40m' ; 

dc.b ' Underline 

dc.b $9b,'3;33;40m , ,$9b, , 5;20H' 

dc.b ' ** Hello World ! ! **',0 



align 
outline: dew ;Output buffer for pchar 

end 

Now that you've done text and character output, its time to move on to 
text input. 



6.4.2 Keyboard input 



You can read keyboard input very easily. You just need to open the I/O 
channel of the CON : window and read from it. You need the READ 
function from the DOS library to do this. Its offset is -42. 

This function has three parameters just like the WRITE function. 

In Dl the handle number that you get from the OPEN function 
In D2 the address that the data read in is to start at 
In D3 the number of bytes to read 

Here is a subroutine that reads the number of characters from the keyboard 
that it finds in D3. It puts them in a buffer. 

Read = -42 ;(6.4.2A) 

getchr: ;* Get (D3) characters from the 

keyboard 
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move.l 


#inbuff,d2 


move.l 


dosbase,a6 


move.l 


conhandle,dl 


jsr 


Read(a6) 


rts 




inbuf f: 


blk.b 80,0 
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;Address of buffer in D2 

JDOS base address in A6 

;Our window handle 

;Call Read function 

pone ! 

;Buf fer for keyboard input 

This routine returns to the main program when <Return> is entered. If 
more then D3 characters are entered, "inbuff ' only gets the first characters. 
The routine gets the remaining characters when called a second time. 

This sort of input is fairly easy. You can backspace, because only the 
characters that should be there are put in the memory block starting at 
"inbuff. The number of characters moved into "inbuff is put in DO. 

Try the program out as follows: 

window, put the following lines in the main 



;Read 80 characters (6.4.2B) 
;Get line from keyboard 
jAddress of the line in A0 
;Null byte on the end 
jOutput line again 



opening 
un: 


the CON : w 


move 


#80,d3 


bsr 


readchr 


lea 


inline, aO 


clr.b 


0(a0,d0) 


bsr 


pmsg 



b P : 



After this comes the code segment that closes the window again. After 
loading the program into the AssemPro debugger, make "bp" a break- 
point and start the program. (SEKA users start the program with "g run" 
and enter "bp" as the breakpoint) The program quits at the breakpoint and 
you can take a look at the results on the screen. Then you can continue 
the program (SEKA with "j bp") and let the window close. 

After starting the program and opening the window, the cursor appears in 
the upper left corner of the window. Enter some text and press <Return>. 
The string that you just entered is output again on the screen. 

You use the "pmsg" routine from the previous chapter to do the output. 
This routine needs a null byte at the end of the text to be output. You put 
a null byte there by putting the address of the input buffer in AO and then 
erasing the byte at A0+D0 using the CLR.B command. Since DO con- 
tains the number of characters that were entered, this byte is the first 
unused byte. 

Since you're in the debugger you can redisplay the disassembled output 
when the program ends to see what "getchar" put in "inbuff (SEKA 
owners can use "q inbuff when the program ends to see what "getchr" put 
there.) You'll find the characters that you typed plus a closing $A. The 
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$A stands for the <Return> key and it's counted too, so if you enter a 12 
and then hit <Return>, for example, DO will contain a three. 

Try this again with a RAW: window. Change the window definition 
from CON: to RAW: and reassemble the program. You'll notice the dif- 
ference right away. After you've entered one character, a return is exe- 
cuted. DO always has a one in it. 

The advantage of this form of input is that cursor and function keys can 
be recognized. Using your own routine, you can repeatedly accept input of 
characters using "getchr" and then work with the special characters. 

There's another form of keyboard input: checking for a single key. This is 
important when a program is about to execute an important function and 
the user must say he wants it executed by entering a "Y" for yes. This can 
be treated as normal input, but in some cases, there is a better method. 

There is a function in the DOS library that waits a certain specified length 
of time for a key to be pressed, and returns a zero (FALSE) if no key was 
hit in this time period. It returns a -1 ($FFFFFFFF = TRUE) if one was. 
To find out which key it takes another function. The WaitForChar func- 
tion, is only good for tasks like waiting for the user to let the program 
know that it can continue scrolling text. 

The function needs two parameters: 

In Dl the handle number of the window or file from which the charac- 
ter should be read. It can also wait for a character from an 
interface. 

In D2 you pass the length of time in microseconds that you should 
wait for a key stroke. 

To wait one second for one key to be hit, you can use the following 
routine: 



WaitForCh=-30- 


-174 


; (6.4.2C) 


scankey: 




;* Wait for a key stroke 


move.l 


conhandle,dl 


;in our window 


move.l 


#1000000,d2 


JWaiting time: one second 


move.l 


dosbase,a6 


;DOS base address 


jsr 


waitf orch (a6) 


;wait ... 


tst.l 


dO 


;Test result 


rts 







The TST command at the end of the program allows the calling routine to 
use a BEQ or BNE command to evaluate the results of the routine — BEQ 
branches if no key was hit. BNE doesn't. 
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Here is an example program in AssemPro format covering what you have 
learned so far. Opening and closing a window, displaying text in the win- 
dow and inputting text: 

;***** 6.4.2A.ASM S.D. ***** 



OpenLib =-30-378 
closelib =-414 
;ExecBase =4 



; Defined in AssemPro 
; Macros 



* calls to Amiga Dos: 



Open 




=-30 


Close 




=-30-6 


Read 




=-42 


Write 




=-48 


IoErr 




=-132 


mode old 


= 1005 


alloc 


abs 


=-$cc 



ILABEL AssemProlincludes /Amiga. 1 ;AssemPro only 



test: 



INIT_AMIGA 


bsr 


init 


bsr 


test 


nop 




bra qu 




move.l 


#mytext,d0 


bsr 


pmsg 


bsr 


pcrlf 


bsr 


pcrlf 


move.l 


#80,d3 


bsr 


getchr 


bsr 


pmsg 



;AssemPro only 



initialization 
;System-Test 

;quit and exit 



;80 characters to read 

(D3) 

;get character 

Joutput line 



rts 



init: 



move.l ExecBase,a6 

lea dosname (pc) ,al 

moveq #0,d0 

jsr openlib(a6) 

move.l d0,dosbase 

beq error 



;System initialization 
and open 

;Number of Execute- 
library 



;Open DOS-Library 



lea 



consolname (pc) ,al 



jConsole Definition 
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move.l 
bsr 
beq 
move.l 



#mode_old,dO 
openf ile 
error 
dO,conhandle 



jConsole open 



rts 



pmsg: 



ploop: 



pmsg2: 



;Print message (dO) 



movem.l d0-d7/a0-a6,- (sp) 
move.l dO,aO 
move.l a0,d2 
clr.l d3 

tst.b (aO) + 
beq pmsg2 
addq.l #l,d3 
bra ploop 

move.l conhandle,dl 

move.l dosbase,a6 

jsr write (a6) 

movem.l (sp) +,d0-d7/a0-a6 

rts 



JCheck length 



pcrlf : 



pchar: 



pchl: 



move #10, dO 
bsr pchar 
move #13, dO 

movem.l d0-d7/a0-a6,- (sp) 
move.l conhandle,dl 

lea outline, al 

move.b d0,(al) 

move.l al,d2 

move.l #l,d3 

move.l dosbase,a6 

jsr write(a6) 

movem.l (sp) +,d0-d7/a0-a6 

rts 



;Character in DO output 
;Save all 



;l letter 



jRestore all 



getchr: 



move.l 


#l,d3 


move.l 


conhandle,dl 


lea 


inbuf f , al 


move.l 


al,d2 


move.l 


dosbase,a6 


jsr 


read(a6) 


clr.l 


dO 


move.b 


inbuf f,d0 


rts 





;Get character for 

keyboard 

;l Character 

;Buffer -Address 
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move.l dosbase,a6 
jsr IoErr (a6) 

move.l d0,d5 



qu: 



move.l #-l,d7 

move.l conhandle,dl 

move.l dosbase,a6 

jsr close(a6) 

move.l dosbase,al 

move.l ExecBase,a6 jsr 

EXIT AMIGA 



;Flag 
jWindow close 



jDOS.Lib close 
Jcloselib (a6) 

jAssemPro only 



openf ile: ;Open File 

move.l al,dl JPointer to 1/0- 

Definit ion -Text 

move.l d0,d2 

move.l dosbase,a6 

jsr open(a6) 

tst.l dO 
rts 



dosname: dc.b 'dos. library ' ,0,0 

Align.w 
dosbase: del 
consolname: dc.b ' CON:0/100/64 0/100/** CLI-Test *■> 

Align.w 

conhandle: del 

mytext:dc.b '** Hello World ! ! **',0 



align 
outline: dew 
inbuff: blk.b 8 

end 



jOutput buffer for pchar 
JInput buffer 



6.4.3 



Printer control 



Now that you've looked at console I/O, let's look at outputting data from 
the computer. The first device that we'll discuss is the printer. 

It's very easy to use the printer. You just need to open another channel. It 
goes just the way you learned it with CON : and RAW: windows; the 
only difference is you enter PRT : instead. 
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You open this channel using the same lines that you used above for the 
window except that the pointer is to the channel name PRT: in Dl. You 
pass the mode "new" (1006) in D2 in the "do_open" routine as well. Save 
the handle number that comes back at a label called "prthandle". 

Now you can use the same output routines that you used with windows 
to send text to the printer. You need to put "prthandle" instead of "con- 
handle" in the line with the "move.l conhandle,dl" command. 

Actually it would be better to eliminate this line from the routine totally. 
Then you can use the same routine for window and printer output. The 
calling procedure would then need to put "conhandle" in Dl for window 
output. It would put "prthandle" in Dl for printer output. This is a very 
flexible output routine that can be used for window and printer output 
now. You can't accept input from the printer, because the printer doesn't 
send data. It just accepts it and prints it. 



6.4.4 Serial I/O 

It's just as easy to use the serial interface as the printer. Just enter SER: 
as the filename. Now you can use the DOS functions READ and WRITE 
just as before to do I/O with the channel you've just opened. You can set 
the parameters for the interface (like Hand shake and Transfer rate) with 
the Preferences program. 



6.4.5 Speech output 



The Amiga has a speech synthesizer built in. This isn't quite as easy to 
program as the I/O devices discussed earlier, however. You use the 
"narrator.device" to do this. 

This device requires several program steps to install it and then causes it 
to speak. You need to open the device, start the I/O, etc... Let's look at 
how to translate the text into the proper form and then output the text. 

First we need to do some initialization. Let's define the constants now. 
Some of them are new. 

;***** Narrator Basic Functions 3/87 S.D. ***** (6.4.5A) 

OpenLib =-408 
closelib =-414 
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ExecBase 



Open =-30 

Close =-36 

mode old =1005 



;Open File 
jClose File 
;01d Mode 



OpenDevice =-444 
CloseDev =-450 



;Open Device 
;Close Device 



Sendlo =-462 

AbortIO =-480 



jStart I/O 
;Abort I/O 



Translate =-30 



translate text 



The initialization routine follows: 



init: 



JInitialize and open system 



;* Open DOS library * 



move.l execbase,a6 



lea 


dosname,al 


moveq 


#0,d0 


jsr 


openlib (a6) 


move.l 


d0,dosbase 


beq 


error 



;Pointer to EXEC library 
;Pointer to DOS name 
;Version: unimportant 
;Open DOS library 
;Save handle 
;Error handle 



Open translator. library 



lea 



transname,al ;Pointer to translator name 



clr.l 


dO 




jsr 


openlib (a6) 


;Open translator 


move.l 


d0,tranbase 


;Save handle 


beq 


error 


jError handling 



;* Set up I/O area for Narrator * 

lea talkio,al ;Pointer to I/O area in Al 

move.l #nwrrep,14 (al) ;Enter port address 

move.l #amaps,48 + 8 (al) ;Pointer to audio mask 

move #4,48 + 12 (al) ;Number of the mask 

move.l #512,36(al) jLength of the output area 

move #3,28 (al) ;Command: write 

move.l #outtext,40 (al) jAddress of output area 

;* Open Narrator device * 



clr.l 


dO 


clr.l 


dl 


lea 


nardevice,a0 


jsr 


opendevice (c 


tst.l 


dO 


bne 


error 



;Number 

;No flags 

;Pointer to device name 

;Open narrator. device 

JError ? 

;Yes ! 



;* Open window 
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lea 


intext,aO 


move.l 


#outtext-intext,dO 


lea 


outtext,al 


move.l 


#512,dl 


move.l 


tranbase,a6 


jsr 


Translate (a6) 
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move.l #consolname,dl ;Console definition 

move.l #mode_old,d2 ;01d mode 

move.l dosbase,a6 ;DOS base address 

jsr 0pen(a6) ;Open window 

tst.l dO jError ? 

beq error ;Yes ! 

move.l dO,conhandle ;Else save handle 

After you've done this initialization, you can have the computer save the 
text you have prepared for it. To see what the Amiga is saying, use the 
"pmsg" function to have the text written in the window: 

move.l #intext,d2 ;Text for Amiga to say 

bsr pmsg ;Output in window also 

sayit: ;Have the text said 

;*Translate the text into a form that the computer can use* 

;Address of the text 
;Length of the text 
;Address of output area 
;Length of output area 
jTranslator base address 
/Translate text 

;* Speech output * 

lea talkio,al ;Address of I/O structure 

move.l #512,36 (al) JLength of output area 

move.l execbase,a6 ;EXEC base address 

jsr SendI0(a6) ;StartI/0 (speech output ) 

Once the program ends, the I/O stops as well, so you need to put in 
something that keeps the program going longer. You'll use the "getchr" 
function that you programmed earlier to take care of this: 

bsr getchr ;Wait for keyboard input 

The computer waits until the <Return> key is pressed. Now you can 
listen to what the Amiga has to say. Once the <Return> key is pressed, 
the program stops. 

qu: ; (6.4.5C) 

move.l execbase,a6 ;EXEC base address 

lea talkio,al ;Pointer to I/O area 

jsr abortio(a6) JStop the I/O 

move.l conhandle,dl 

move.l dosbase,a6 

jsr close(a6) ;Close window 
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move.l dosbase,dl 

move.l execbase,a6 

jsr closelib(a6) ;Close DOS library 

lea talkio,al 

jsr closedev (a6) ;Close narrator. device 

move.l tranbase,al 

jsr closelib(a6) ;Close translator library 

rts ;* End of program 

Now comes the data that you need for the program above: 

mytext: dc.b ' This is a test text !' ,10,13,10,13,0,0 

dosname: dc.b ' dos. library ' ,0,0 

transname". dc.b "translator. library", 

consolname: dc.b ' RAW:0/100/640/100/** Test window' ,0 

nardevice: dc.b ' narrator. device ' ,0 

align 

dosbase: del 

tranbase: del 

amaps: dc.b 3,5,10,12 

align 

conhandle: del 

talkio: blk.l 20,0 

nwrrep: blk.l 8,0 

intext: dc.b ' hello, i am the amiga talking to you ' ,0 

align 

outtext: blk.b 512,0 

This is quite a bit of work, but it's worth it because it opens so many 
possibilities for you. There are a lot of variations possible if you modify 
parameters. These parameters are entries in the I/O area starting at the 
"talkio" label. The area is built as follows: 



131 



6. Amiga Operating System 



Amiga Machine Language 



Offset 



Length 



Meaning 



** Port Data ** 







L 


4 


L 


8 


B 


9 


B 


10 


L 


14 


L 


18 


W 


** I/O Data ** 




20 


L 


24 


L 


28 


W 


30 


B 


31 


B 


32 


L 


36 


L 


40 


L 


44 


L 


** Narrator data items ** 


48 


W 


50 


W 


52 


W 


54 


W 


56 


L 


60 


W 


62 


W 


64 


W 


66 


B 


67 


B 


68 


B 



Pointer to next block 

Pointer to last block 

I/O type 

Priority 

Pointer to I/O name 

Pointer to port 

Length 

Pointer to Device 
Pointer to Device Unit 
Command word 
I/O flags 
I/O status 
I/O pointer 
I/O length 
Pointer to data 
I/O offset 

Speech speed 

Highness of voice 

Speech mode 

Sex (male/female voice) 

Pointer to audio mask 

Number of mask 

Volume 

Read in rate 

Flag for producing graphics (0=off) 

Actual mask (internal use) 

Channel used (internal use) 



We wouldn't recommend experimenting with the data in the first two 
blocks. If you do, you can easily cause a system crash. You can use the 
last entries of the structure to produce some interesting effects though. 

Here's an overview of the parameters you can use to vary the speech out- 
put. The value in parenthesis is the standard value, the value set when 
narrator .device is opened 

Speech speed (150) 

You can use this to set the speed of speech. The pitch of the voice is not 
affected by this value. 
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Pitch of voice (110) 

You can choose a value between 65 and 320 for the pitch (from Goofy to 
Micky Mouse). 

Speech mode (0) 

The zero gives half-way natural speech. A one lets the Amiga speak in 
monotone like a robot. 

Sex (0) A zero means masculine and a one means feminine (more or less ...). 

Volume (64) The volume can range from to 64. The standard value is the loudest 
possible. 

Read in rate (22200) 

By lowering this value, the voice is lowered. If you change this very 
much, you'll get some weird voices! 

You can experiment a bit until you find an interesting voice. Have fun! 

Here is a complete talking program in AssemPro format: 

j***** Speech output S.D. ***** 



Jdef ined by AssemPro 



OpenLib 


=-30-378 


closelib 


=-414 


jExecBase 


=4 


* calls to Amiga Dos: 


Open 


=-30 


Close 


=-30-6 


opendevice 


=-444 


CloseDev 


=-450 


addport 


=-354 


RemPort 


=-360 


;DoIo 


=-456 


SendIO 


= -462 


AbortIO 


= -480 


Read 


=-30-12 


Write 


=-30-18 


;MyInput 


=-30-24 


;Output 


=-30-30 


;CurrDir 


=-30-96 


;Exit 


=-30-114 


WaitForCh 


=-30-174 


FindTask 


=-294 


Translate 


=-30 


mode old 


= 1005 


;mode new 


= 1006 


;alloc abs 


=-$cc 


;free mem 


=-$d2 
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! ! ! when > 500KB ! 
org $40000 
load $40000 



or place in chip memory 



'!!!!!!!!! 



ILABEL AssemPro:includes/Amiga.l ;AssemPro only 
INIT_AMIGA ;AssemPro only 



run: 



init: 



bsr 
bra 



init 
test 



move.l 


ExecBase,a6 




lea 


dosname (pc) 


,al 


moveq 


#0,d0 




jsr 


openlib (a6) 




move.l 


d0,dosbase 




beq 


error 





move.l ExecBase,a6 

lea transname,al 

clr.l dO 

jsr openlib (a6) 

move.l d0,tranbase 

beq error 

sub.l al,al 

move.l ExecBase,a6 

jsr FindTask(a6) 

move.l d0,nwrrep+2 



Jlnitialization 
;System-Test 

;System initialization 

;and open 

;Pointer to EXEC library 

JPointer to DOS name 

jVersion: not important 

;Open DOS-Library 

;Save handle 

jError routine 

;Open translator 

library 

JPointer to EXEC library 

;Pointer to translator 

;name 

jOpen Translator 
;Save handle 
JError routine 
;Set up 



;Find Task 



b P : 



lea 


nwrrep,al 


jsr 


addport (a6) 


lea 


talkio,al 


move.l 


#nwrrep,14 (al) 


clr.l 


dO 


clr.l 


dl 


lea 


nardevice,a0 


jsr 


opendevice (a6) 


tst.l 


dO 


bne 


error 



lea talkio,al 

move.l #nwrrep,14 (al) 

move.l #amaps,48 + 8 (al) 

move #4,48 + 12 (al) 



;Add Port 

;Open narrator device 

JPointer to I/O area in 

JA1 

JEnter Port address 

jNumber 

JNo flags 

JPointer to device name 

jOpen Narrator. device 

JError? 

jYes! 

jSetup I/O for narrator 

Jdevice 

JPointer to I/O in Al 
JEnter port address 
JPointer to audio mask 
JSize of Mask 
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lea consolname (pc) ,al 

move.l #mode_old,dO 

bsr openfile 

beq error 

move.l dO,conhandle 

rts 



;Console-Def in it ion 
jConsole open 



test: 



move.l #MyText,dO 
bsr pmsg 



bsr 



sayit 



bsr readln 

move #10,d0 

bsr pchar 

move.l #inline + 2,d0 

bsr pmsg 

bsr pcrlf 

bra qu 



;Test-Text output 
;Say text 
Jlnput 
;LF output 
;and again 



move.l #-l,d7 
qu: 

move.l ExecBase,a6 lea 

jsr abortio(a6) 

move.l conhandle,dl 

move.l dosbase,a6 

jsr close(a6) 

move.l dosbase,al 

move.l ExecBase,a6 

jsr closelib(a6) 

lea nwrrep,al 

jsr RemPort (a6) 

lea talkio,al 

jsr closedev(a6) 

move.l tranbase,al 

jsr closelib(a6) 



EXIT_AMIGA 

openfile: 

move.l al,dl 

move.l d0,d2 

move.l dosbase,a6 

jsr open (a6) 

tst.l dO 
rts 

pmsg: 



;Flag 
talkio,al 

;Window close 
jDOS.Lib close 



jRemove port 

Jclose narraror device 

;Close translator 
Jlibrary 

;AssemPro only 

;Open File 
;pointer to 1/0- 
De fin it ion- Text 



;Print message (dO) 
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messl: 



mess2: 



movem.l d0-d7/a0-a6,- 


(sp) 


move.l 


dO,aO 




move.l 


a0,d2 




clr.l 


d3 




tst.b 


(a0) + 




beq 


mess2 




addq.l 


#l,d3 




bra 


messl 




move.l 


conhandle,dl 




move.l 


dosbase,a6 




jsr 


write (a6) 





;Length calculate 



movem.l ( sp) + ,dO-d7/aO-a6 
rts 



pcrlf : 



pchar: 



pchl: 



move 


#10, dO 


bsr 


pchar 


move 


#13,d0 



movem.l dO-d7/aO-a6,- (sp) 
move.l conhandle.dl 



;Output character in DO 
;save all 



lea 


chbuf f,al 


move.b 


d0,(al) 


move.l 


al,d2 


move.l 


#l,d3 


move.l 


dosbase, a6 


jsr 


write (a6) 


movem.l 


(sp) +,d0-d7/a0-a6 


rts 




scankey". 




move . 1 


conhandle,dl 


move . 1 


#500,d2 


move . 1 


dosbase, a6 


jsr 


waitf orch (a6) 


tst.l 


dO 


rts 




readln: 




movem.l d0-d7/a0-a6,- (sp) 


lea 


inline + 2,a2 


clr.l 


(a2) 


inplop: 




bsr 


getchr 


cmp.b 


#8,d0 


beq 


backspace 


cmp.b 


#127,d0 


beq 


backspace 


bsr 


pchar 


cmp.b 


#13,d0 


beq 


inputx 


move.b 


d0,(a2) + 


bra 


inplop 



;l letter 

Jrestore all 

JTest key 
;Wait value 



JInput from keyboard 
;save registers 
jPointer to input buffer 



jDelete ? 
jCharacter output 
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inputx: 



clr.b (a2) + 
sub.l #inline,a2 
move a2, inline 
movem.l (sp) +,d0-d7/a0-a6 
rts 



JLenght in inline+1 
JRegisters 



backspace: 




cmp.l 


#inline,a2 


beq 


inplop 


move.b 


#8,d0 


bsr 


pchar 


move 


#32,d0 


bsr 


pchar 


move 


#8,d0 


bsr 


pchar 


clr.b 


(a2) 


subq.l 


#l,a2 


bra 


inplop 



;At the beginning? 
;yes 

jBackspace 

;Blank 

jBackspace 



getchr: 



move.l 


#l,d3 


move.l 


conhandle,dl 


lea 


inbuf f,al 


move.l 


al,d2 


move.l 


dosbase,a6 


jsr 


read (a6) 


clr.l 


dO 


move.b 


inbuf f,dO 


rts 





;Get one character from 

Jkeyboard 

;One character 

jBuffer- Address 



sayit: 



lea 


intext,aO 


move.l 


#outtext-intext,dO 


lea 


outtext,al 


move.l 


#512, dl 


move.l 


tranbase,a6 


jsr 


Translate (a6) 


lea 


talkio,al 


move 


#3,28 (al) ;?? 


move.l 


#512,36(al) 


move.l 


#outtext,40 (al) 


move.l 


ExecBase,a6 


jsr 


sendio (a6) 



MyText: 
do s name: 
transname: 
align. w 
dosbase: 
tranbase: 



dc.b 'This is our Test-Text 

dc.b • dos. library * ,0,0 

dc.b "translator. library", 

del 
del 



',10,13,10,13,0,0 
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consolname: dc.b 'CON:0/100/640/100/* Speech-Test S.D.* ',0 

nardevice: dc.b ' narrator. device' ,0 

amaps: dc.b 3,5,1 0,12,0,0 

align.w 

conhandle: del 

inbuff: blk.b8 

inline: blk.b 180,0 

chbuf f : blk.b 82,0 

narread: blk.l 20,0 

talkio: blk.l 20,0 

nwrrep: blk.l 8,0 

intext: dc.b 'hello, i am the amiga computer ',0 

align.w 

outtext: blk.l 128,0 

end 
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6.5 Disk operations 



The most important peripheral device for a computer like the Amiga is 
the disk drive. You use it to save data, so that you don't lose it when you 
turn off the computer. We'll look at saving and retrieving data in this 
chapter. 

Let's first look at the simple disk operations that are used for data man- 
agement. To gain access to a file, you must open it first. This is done 
using the OPEN function from the DOS library, a function that you're 
already familiar with. I'll assume in the following examples, that you've 
already opened the DOS library. 



6.5.1 Open files 



The OPEN function needs a parameter for the mode. The mode has a par- 
ticular meaning. If the file is opened for reading, it must already exist. 
The mode for the OPEN function must be "old" (1005) in this case. 

If you want to produce a file, you must open it first. Since it doesn't 
exist, you use the "new" (1006) mode. If a file is opened for writing 
using this mode even though a file with this name already exists, the old 
file with this name is erased and replaced. To avoid loss of data, you 
should check if a file by that name already exists and then output an error 
message if it does. 

You're going to start with a subroutine that opens a file. Let's assume 
that the filename starts at the label "filename", and that it is closed with a 
null byte. You just need to pass the mode in register D2. 

The routine puts the file handle number in "filehd" and returns to the 
main program. Since the operation with the handle is the last one 
performed by the subroutine, the status of the operation can be evaluated 
once the return has been executed. If the operation went smoothly and the 
file is opened, the handle number has a non-zero value. If it is zero and 
"bsr openfile" is followed by "beq error", you can branch to an error hand- 
ling routine when problems occur. 
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Open 


-30; 


Close 


-36 


Mode old = 


1005 


Mode new = 


1006 


openf ile: 




move.l 


dosbase,a6 


move.l 


#f ilename,dl 


jsr 


Open (a6) 


move.l 


dO.filehd 


rts 




closef ile: 




move.l 


dosbase,a6 


move.l 


filehd,dl 


jsr 


Close (a6) 


rts 




filehd: 


del 


filename: 


dc.b "Filename", 


align 





6. Amiga Operating System Amiga Machine Language 

Here is the subroutine for opening and closing a file. 

(6.5.1A) 



;* Open file, mode in DO 
;DOS base address in A6 
jPointer to file name 
;Open file 
JSave handle 

;* Close file 
JDOS base address in A6 
JFile handle in Dl 
JClose file 

JStorage for File handle 
jFile to be opened 
Jeven 

To use these routines, you must look at how you can load and save data. 



6.5.2 Reading and writing data 

Let's write a new file. To start, write the following lines: 

move.l #Mode_new,d2 ;Open new file (6.5.2A) 
bsr openfile ;Open file 
beq error ;Didn'twork! 

For the filename, write a name like "Testfile" in the line labled 
"filename". After calling the "openfile" routine, a file with this name is 
created on the disk. If one existed already, it is erased. 

Let's assume you want to write a short text to the file. For the example 
let's use: 

text: dc.b "This is a test text for the Test file", 
textend: 

The "textend" label is used so that you can calculate the number of data 
bytes by subtracting "text". 

You want to write this text in the file. Use the WRITE function which 
needs three parameters: 
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In Dl the file handle that you got back from the OPEN function 
In D2 a pointer to the data that should be written 
In D3 the number of bytes to be written 

For the example, you'll need another segment of code to put the pointer 
to the data in D2 and the number of bytes in D3: 



Write = -48 




; (6.5.2B) 


writedata: 




;* Write data in the file 


move.l 


dosbase,a6 


;DOS base address in A6 


move.l 


filehd,dl 


;File handle in Dl 


jsr 


Write (a6) 


;Write data 


rts 







After opening the file, you can call the subroutine from the main program 
with the following lines: 

move.l #text,d2 ;Pointer to data 

move.l #textend-text,d3 JNumber of bytes 
bsr writedata ;Write data in the file 

Then close the file with: 

bsr closefile ;Close file 

bra end ;End program 

After running the program, look at the directory of the diskette, you 
should find the file "testfile". It is just as long as your text. You want to 
read this file in, to make sure that it contains the right data. 

You need the DOS function READ, which needs the same parameters as 
the WRITE function. You can use parameters for the number of bytes to 
read just part of the file. If you give a larger number than the file con- 
tains, the whole file is loaded. You'll find the number of bytes read in 
DO. 

Let's set up a field that has enough space for the data you want to read. 
You can do this with the following line: 

field: blk.b 100 ;Reserve 100 bytes 

For the example data, this is plenty. If you want to load another file, you 
may need to reserve more space. 

Now let's write a subroutine to read the data. You always want to load 
whole files. You just need to pass the address of the buffer so the data is 
loaded into the subroutine. In the example, it's the address "field". 
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Here's the subroutine that reads the entire opened file into the memory 
area pointed to by D2: 



Read = -4 2 




; (6.5.2C) 


readdata: 




;* Read file 


move.l 


dosbase,a6 


JDOS base address in A6 


move.l 


filehd,dl 


jFile handle in Dl 


move.l 


#$ffffff,d3 


;Read an arbitrary number o 
bytes 


jsr 


Read(a6) 


JRead data 


rts 







To use this routine to load the file into the buffer "field", use the follow- 
ing main program: 



move.l 


#Mode_old,d2 


|01d file 


bsr 


openf ile 


;Open file 


beq 


error 


JDidn ' t work ! 


move.l 


#field,d2 


;Pointer to data buffer 


bsr 


readdata 


JRead file 


move.l 


d0,d6 


JSave number of bytes in D6 


bsr 


closef ile 


;Close file 


bra 


end 


;Program end 



After assembling and starting this program, you can use the debugger to 
look at the data buffer that you filled with data from the file. In D6, 
you'll find the number of bytes that were read from the file. 



6.5.3 Erase files 



Once you've experimented enough with the program above, you'll cer- 
tainly want to erase the "Testfile" file. The DELETEFILE function in the 
DOS library has an offset of -72. It only needs one parameter. The para- 
meter is passed in Dl. The parameter is a pointer to the filename. The 
name must be closed with a null byte. 

To erase "Testfile", use the following lines: 

DeleteFile = -72 ; (6.5.3) 

move.l dosbase,a6 JDOS base address in A6 

move.l #filename,dl JPointer to file name in 

Dl 
jsr DeleteFile (a6) JErase file 
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The file is deleted. You can't save the file with normal methods if you 
accidently erase it! You can use a trick that saves the data. We'll take a 
look at this trick later. It's used in lots of programs. 



6.5.4 Rename files 



When a text editing program writes a text that has been altered back to 
disk, the old file usually isn't erased. Often the old file is renamed. For 
example, it might get the name "Backup". Then the new file is written to 
disk with the old name. 

The function in the DOS library that allows you to change the names of 
programs is called RENAME and has -78 as an offset. You need to pass 
two parameters — Dl as a pointer to the old name and D2 as a pointer to 
the new name of the file. 

To rename "Testfile" as "Backup" (before you erase it), use the following 
lines: 

Rename = -78 

move.l dosbase,a6 ;DOS base addressin A6 

move.l #oldname,dl ;Pointer to old name in Dl 

move.l #newname,d2 ;Pointer to new name in D2 

jsr Rename (a6) ;Rename file 

oldname: dc.b "Test file", 
newname: dc.b "Backup",0 



6.5.5 cli directory 



Let's pretend that you've programmed a text editor and started it. Now 
you want to load a text from disk and edit it — but what's the name of that 
file? 

You need a function to read and display the directory of a disk. There are 
several ways to do this. First let's use the easiest method. It doesn't re- 
quire much programming and can be quite useful. 

The trick is to call the Dir or List programs that are in the C directory. 
You'll use the CLI commands. The DOS library contains a command 
called "Execute" with offset -222 that allows you to execute CLI com- 
mands. 
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The function needs three parameters: 



InDl 



InD2 



InD3 



a pointer to a string closed with a zero that contains the name of 
the command to be executed. This string must contain the same 
command that you would give in the CLI. It can be a null 
pointer as well. 

the input file is determined. Normally there's a zero here. If, 
however, you give the file handle of a text file, though, this file 
is read and interpretted as a command sequence. If you define a 
window as the input medium, you've programmed a new CLI 
window! 

the output file is determined. If there's a zero here, the output of 
the commands (for example, DIR output) is sent to the standard 
CLI window. 



To try this out, insert this subroutine in a program that has already 
opened the DOS library and a window. 



Execute - -222 


; (6.5.5) 


dirl 






move.l 


dosbase,a6 


;DOS base address in A6 


move.l 


#command,dl 


jPointer to command line 


clr.l 


d2 


;No input (CLI window) 


move.l 


conhandle,d3 


;Output in our window 


jsr 


Execute (a6) 


jExecute command 


rts 






command: 







dc.b 



"dir",0 



This program works with the List command as well. The disadvantage of 
this method is that the disk that the Workbench is loaded from must be in 
the drive or the system requests you to put it in. The Dir command is just 
a program, and the Amiga must load it before it can run. 

This disadvantage isn't too great. The program is short, and it allows you 
to use any CLI command in a program. 

Here is the complete program in AssemPro format that calls the Dir 
program: 

; ***** 6.5.5 ADIR. ASM S.D. ***** 



OpenLib 

closelib 

jExecBase 



= -408 

=-414 
= 4 



; Defined in AssemPro 
Macros 



* calls to Amiga Dos: 
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Open 


=-30 


Close 


=-36 


Execute 


= -222 


IoErr 


=-132 


mode old 


= 1005 


alloc abs 


=-$cc 



ILABEL AssemPro:includes/Amiga.l ;AssemPro only 
INIT_AMIGA jAssemPro only 



bsr 
bra 



mit 
test 



mit: 



move.l ExecBase,a6 

lea dosname (pc) ,al 

moveq #0,d0 

jsr openlib(a6) 

move.l d0,dosbase 

beq error 

lea consolname (pc) ,al 

move.l #mode_old, dO 

bsr openfile 

beq error 

move.l d0,conhandle 

rts 



JInitialization 
;System-Test 

jSystem initialization 
jand open 

JNumber of Execute- 
; library 



jOpen DOS-Library 

jConsole Definition 
jConsole open 



test: 



dir: 



bsr dir 




bra qu 




move.l 


dosbase,a6 


move.l 


#command,dl 


clr.l 


d2 


move.l 


conhandle,d3 


jsr 


Execute (a6) 


rts 





;do directory 
Jquit and exit 



;DOS base address in A6 
jPointer to command line 
;No input (CLI window) 
Joutput in our window 
jexecute command 



error: 



qu: 



move.l dosbase,a6 

jsr IoErr(a6) 

move.l d0,d5 

move.l #-l,d7 

move.l conhandle,dl 

move.l dosbase,a6 

jsr close(a6) 



;Flag 
;Window close 
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move.l dosbase,al 
move.l ExecBase,a6 
jsr closelib(a6) 



jDOS.Lib close 



EXIT AMIGA 



;AssemPro only 



openf ile: ;Open File 

move.l al,dl ;Pointer to 1/0- 

; Definition-Text 

move.l d0,d2 

move.l dosbase,a6 

jsr open(a6) 

tst.l dO 
rts 



dosname: dc.b ' dos. library ' ,0,0 

Align.w 
dosbase: del 
consolname: dc.b ■ CON:0/100/64 0/1 00/** CLI-Test **',0 

Align.w 
conhandle: del 
command: 

dc.b "dir",0 



end 



6-5.6 Read directory 



Now, let's look at another method that doesn't need the CLI. In this way, 
you can read the directory of any disk without having to play Disk 
Jockey. 

You need to write a program that does what CLI's Dir program does. 
There are several steps. 

First you must give the system a key to the desired directory. That means 
you must call DOS' Lock function. It needs two parameters: 

In Dl pass a pointer to a text that contains the name of the directory 
you wish to read. If, for example, you want to read the contents 
of the RAM disk, the text would be 'RAM:',0. 

In D2 put the mode that determines whether to read or write. Let's use 
the "Read" (-2) mode. 
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You call the Lock function (Offset -84) and get either a pointer to the key 
or a zero returned to you in the DO register. If you get a zero, the call 
didn't work, the file wasn't found. This function can be used to find if a 
file is on the disk. You use this function with the name and see if DO 
comes back zero. If not, the file exists. 

Let's assume the file or path exists. You need to save the value that came 
back in DO. You'll need it for both functions that you'll call. 

The next function you need is called Examine. You use it to search the 
disk for an acceptable entry. It returns parameters like name, length and 
date that correspond to the entry. You need to reserve a memory block for 
this information and put the beginning of the block in D2 before calling 
the Examine function. Put the key that you got from the Lock function 
in theDl register. 

The memory area that is filled with information is called a FilelnfoBlock. 
It's 260 bytes long and contains information about the file. The name 
starts in the 9th byte and ends with a null byte, so you can easily print it 
with our "pmsg" routine. The information that Examine gives isn't about 
a particular file, but about the disk. The name in FilelnfoBlock is the disk 
name. 

The Examine function sends the status back in the DO register. Since the 
Lock function already tested if the file existed, evaluating the status really 
isn't necessary. 

Now to the function that you can use to read individual files from the 
directory. The function is called ExNext (Examine Next). This function 
searches for the next entry that fits the key every time it is called. ExNext 
gets the same parameters as Examine gets. However, the return parameter 
in DO is more important here. 

The ExNext function is always called in the same way. It always gets the 
next entry of the directory. If no more entries exist in the directory, Ex- 
Next puts a zero in the DO register. 

You need to continue performing this operation until there aren't any 
more entries. You can find this using the IoErr function from the DOS 
library. 

This function doesn't need any parameters. It returns the status of the last 
I/O operation that was performed in the DO register. After the last Ex- 
Next, this value is 232, which means no more Entries. 
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Here's a complete routine for reading the directory of the disk in drive 
DFO: and displaying the contents in the window. 

J6.5.5B.ASM 

;***** DOS-Sample function 3/87 S.D. ***** 

OpenLib =-30-378 

closelib =-414 
ExBase =4 

* calls to Amiga Dos: 



Open 


= -3 


Close 


= -30-6 


Read 


= -30-12 


Write 


= -30-18 


Mylnput 


= -30-24 


Output 


= -30-30 


CurrDir 


= -30-96 


Lock 


= -30-54 


Examine 


= -30-72 


ExNext 


= -30-78 


Exit 


= -30-114 


IoErr 


= -30-102 


WaitForCh 


= -30-174 


Mode 


= 


mode old 


= 1005 


mode new 


= 1006 


alloc abs 


= -$cc 


free mem 


= -$d2 



ILABEL AssemProlincludes/Amiga.l jAssemPro only 

JAssemPro only 



INIT_ 


_AMIGA 


bsr 


init 


bra 


test 



Jlnitialization 
JSystem-Test 

init: jSystem initialization 

;and open 

move.l ExBase, a6 jPointer to EXEC library 

lea dosname (pc) ,al 

moveq #0,d0 

jsr openlib(a6) ;Open DOS-Library 

move.l d0,dosbase 

beq error 

lea consolname (pc) ,al ;Console-Def inition 

move.l #mode_old,d0 

bsr openf ile JConsole open 

beq error 

move.l d0,conhandle 

rts 
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test: 



loop: 



move.l 


#MyText,dO 


bsr 


pmsg 


move.l 


dosbase,a6 


move.l 


#name,dl 


move.l 


#-2,d2 


jsr 


Lock (a6) 


move.l 


d0,d5 


tst.l 


dO 


beq 


error 


move.l 


dO,locksav 


move.l 


dosbase,a6 


move.l 


locksav,dl 


move.l 


#fileinfo,d2 


jsr 


Examine (a6) 


move.l 


d0,d6 


tst.l 


dO 


beq 


error 


move.l 


dosbase,a6 


move.l 


locksav,dl 


move.l 


#fileinfo,d2 


jsr 


ExNext (a6) 


tst.l 


dO 


beq 


error 


move.l 


#f ileinf o + 8,d0 


bsr 


pmsg 


bsr 


pcrlf 


bra 


loop 



;Test-Text output 



qu: 



move.l dosbase,a6 

jsr IoErr(a6) 

move.l d0,d6 

move.l #presskey,dO 

bsr pmsg 

bsr getchr 

move.l #-l,d7 

move.l conhandle,dl 

move.l dosbase,a6 

jsr close(a6) 

move.l dosbase,al 

move.l ExBase,a6 

jsr closelib(a6) 



;Flag 
;Window close 

JDOS.Lib close 



EXIT AMIGA 



openf ile: 



;AssemPro only 
;Open File 
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move.l al,dl 



pmsg: 



messl: 



mess2: 



move.l 


d0,d2 




move.l 


dosbase,a6 




jsr 


open (a6) 




tst.l 


dO 




rts 






movem.l d0-d7/a0-a6,- 


(sp) 


move.l 


dO,aO 




move.l 


a0,d2 




clr.l 


d3 





tst.b 
beq 
addq.l 
bra 



(a0) + 
mess2 

#l,d3 
messl 



move.l conhandle,dl 
move.l dosbase,a6 
jsr write (a6) 

movem.l (sp) +,d0-d7/a0-a6 

rts 



;pointer to I/O- 
; Definition-Text 



;Print message (dO) 



pcrlf : 



pchar: 



pchl: 



move 

bsr 

move 



#10,d0 

pchar 

#13,d0 



movem.l d0-d7/a0-a6,- (sp) 
move.l conhandle,dl 



lea 


chbuf f,al 


move.b 


dO,(al) 


move.l 


al,d2 


move.l 


#l,d3 


move.l 


dosbase,a6 


jsr 


write (a6) 


movem.l 


(sp) +,d0-d7/a0-a6 


rts 




scankey: 




move.l 


conhandle,dl 


move.l 


#500,d2 


move.l 


dosbase,a6 


jsr 


waitf orch (a6) 


tst.l 


dO 


rts 




readln". 





movem.l d0-d7/a0-a6,- (sp) 

lea inline + 2,a2 
clr.l (a2) 



inplop: 



jCharacter in DO output 
;save all 



Jrestore all 

;Test key 
;Wait value 



;input from keyboard 

;Registers 

JPointer to input buffer 



bsr 



getchr 
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cmp.b 

beq 

cmp.b 

beq 

bsr 

cmp.b 

beq 



Input: 



#8,d0 

backspace 
#127,d0 
backspace 

pchar 
#13,d0 
Inputx 



move.b d0,(a2) + 



bra 



clr.b 
sub.l 
move 



.nplop 
(a2) + 



#inline,a2 
move a2, inline 
movem.l (sp)+,d0-d7 
rts 



jDelete ? 
jCharacter output 



jLength in inline+1 
/a0-a6 Registers 



backspace: 






cmp.l 


#inline,a2 


;at beginning? 


beq 


inplop 


;yes 


move.b 


#8,d0 




bsr 


pchar 


jBackspace 


move 


#32,d0 




bsr 


pchar 


;Blank 


move 


#8,d0 




bsr 


pchar 


jBackspace 


clr.b 


<a2) 




SUbq.l 


#l,a2 




bra 


inplop 




getchr: 




;Get one character from 
;keyboard 


move.l 


#l,d3 


;l character 


move.l 


conhandle,dl 




lea 


inbuf f,al 


;Buf fer- Address 


move.l 


al,d2 




move.l 


dosbase,a6 




jsr 


read (a6) 




clr.l 


dO 




move.b 


inbuff,dO 




rts 







MyText: dc.b 'Directory of diskette: DFO : ',10,13,10,13,0,0 

dosname: dc.b ' dos . library ' ,0,0 

presskey: dc.b 'Press the RETURN key!!',0 

align . w 
dosbase: del 

consolname: dc.b • CON : 0/100/640/100/** Directory-Test **',0 
name: dc.b 'DFO: ',0 



al 


ign .w 




locksav: 


del 





f ileinf o: 


ds.l 


20 


conhandle 


: del 





inbuf f : 


DS.B 


8 


inline : 


DS.B 


180 


chbuff : 


DS.B 


82 
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DiskKey.L 


4 


DirEntryType.L 


8 


FileName 


116 


Protection.L 


120 


En try Type .L 


124 


Size.L 


128 


NumBlocks.L 


132 


Days.L 


136 


Minute.L 


140 


Tick.L 


144 


Comment 



end 



The FilelnfoBlock contains the following entries: 

Offset Name Meaning 

Disk number 

Entry type (+ = Directory, - = File) 

108 bytes with the filename 

File protected? 

Entry type 

Length of file in bytes 

Number of blocks 

Creation day 

Creation time 

Creation time 

116 bytes with comments 

If you want to have the program output the file length as well, you can 
read the length with "move.l fileinfo+124,d0" and then use a conversion 
routine to produce a decimal number. You can output this result with the 
name. 



6.5.7 Direct access to disk 

There isn't a simple function in the library for accessing single disk 
sectors. Here, you must work with a device just like you did with speech 
output. This time you'll be working with the trackdisk.device. 

You want to work with this device to directly program the disk drives. 
Once you've built up the necessary program machinery, you can experi- 
ment with various commands for disk access. Remember that an error can 
cause the disk to be modified and thus unusable. Make sure you're using a 
non-essential disk. Don't use one which contains your only copy of 
something. 

The initialization here is similar to that for speech output. Here's the ini- 
tialization routine for the program: 

;** Direct disk access via trackdisk.device ** (6.5.6) 



OpenLib 


=-408 


closelib 


=-414 


ExecBase 


=4 


Open 


=-30 


Close 


=-36 
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opendevice =- 


■444 




CloseD* 


ev 


■450 




Sendlo 


=- 


-462 




Read 


=- 


-30-12 




Write 


=- 


■30-18 




WaitForCh 


■30-174 




mode o 


Id =1005 




run: 










bsr 


init 


;lnitialization 




bra 


test 


;System test 


init : 






JInitialize and open 
Jsystem 




move.l 


execbase,a6 


;Pointer to EXEC library 




lea 


dosname,al 






moveq 


#0,d0 






jsr 


openlib (a6) 


;Open DOS library 




move.l 


d0,dosbase 






beq 


error 






lea 


diskio,al 


;Pointer to disk I/O area 




move.l 


#diskrep,14 (al) 


jPointer to port 




clr.l 


dO 


jDrive (built in) 




clr.l 


dl 


;No flags 




lea 


trddevice,a0 


JPointer to device name 




jsr 


opendevice (a6) 


;Open trackdisk. device 




tst.l 


dO 


jError? 




bne 


error 


;Yes! 




move.l 


#consolname (pc) ,dl 


jConsole definition 




move.l 


#mode old,d2 


;01d mode 




move.l 


dosbase,a6 


;DOS base address 




jsr 


open (a6) 


jOpen window 




tst.l 


dO 


;Error? 




beq 


error 


;Yes! 




move.l 


d0,conhandle 


;Else save handle 




rts 




JDone 


test: 






;Place for test routine 



And now for the functions that take care of the various messages at the 
end of the program. 



error: 








move.l 


#-l,d7 


qu: 








move.l 


execbase,a6 




lea 


diskio,al 




move.l 


32 (al),d7 




move 


#9,28(al) 




move.l 


#0,36(al) 




jsr 


sendio (a6) 




move.l 


conhandle,dl 




move.l 


dosbase,a6 




jsr 


close (a6) 




move.l 


dosbase,dl 




move.l 


execbase,a6 




jsr 


closelib (a6) 




lea 


diskio,al 



;Flag for error (forSEKA) 

JEXEC base address 

JPointer to disk I/O 

;I0_ACTUAL in D7 (for testing) 

;Command: motor on/off 

;0=of f, l = on, so turn motor 

;off 

;Close window 



;Close DOS. Lib 
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]sr 
rts 



closedev (a6) jClose trackdisk. device 



Let's not forget the routine that waits for the user to press <Return>, so 
that you can watch the effects of the test function in peace: 



getchr: 







;Get a character from keyboard 


move.l 


#l,d3 


;l character 


move.l 


conhandle,dl 


jWindow handle 


move.l 


#inbuff,d2 


;Buf fer address 


move.l 


dosbase,a6 


;DOS base address 


jsr 


read (a6) 


;Read character 


rts 




;That ' s it 



The last thing you need is the section of code that declares the text and 
data fields that your program needs: 



dosname: dc.b 

align 
consolname: dc.b 



align 
trddevice: 

align 
dosbase: 
conhandle: 
inbuf f : 
diskio: 
diskrep: 
diskbuf f : 



dc.b 

del 
del 
blk.b 80,0 
blk.l 20,0 
blk.l 8,0 



'dos. library ' ,0 

•RAW:0/100/640/50/** Wait 
Window' ,0 

•trackdisk. device ' ,0 

JDOS base address 

;Window handle 
jKeyboard buffer 
;i/0 structure 
;i/0 port 



blk.b 512*2,0 ;^ lace for 2 sectors 



There, now you're done with the set-up work. Let's look at how you can 
give commands to the disk drives. The first and easiest command, is the 
one for turning the drive motor on and off. You've already seen this com- 
mand in the program. This is command number nine. This number goes 
in the command word of the I/O structure (bytes 28 and 29 of the struc- 
ture). 

You need to pass a parameter that lets the computer know whether to turn 
the motor off or on. This information goes in the I/O long word that 
starts at byte 36; it's zero for off, and one for on. 

You already chose the motor that should be turned on or off when you 
opened the device. You put the number of the chosen disk drive in DO — 
in your case you put a zero there because you are using the DF0: disk 
drive. 

Here's an overview of the commands you can use to access information 
on the disk: 
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No. Name Function 



2 


READ 


Read one or more sectors 


3 


WRITE 


Write sectors 


4 


UPDATE 


Update the track buffer 


5 


CLEAR 


Erase track buffer 


9 


MOTOR 


Turn motor on/off 


10 


SEEK 


Search for a track 


11 


FORMAT 


Format tracks 


12 


REMOVE 


Initialize routine that is called when you 
remove the disk 


13 


CHANGENUM 


Find out number of disk changes 


14 


CHANGESTATE 


Test if disk is in drive 


15 


PROTSTATUS 


Test if disk is write protected 



You've already learned about command number nine. Let's look at the 
three commands you can use to make tests. These are the last three com- 
mands. They put a return value in the long word that begins in the 32nd 
byte in the I/O structure. This value was written to D7 in the program 
above for testing purposes. You can read its contents directly if you ran 
the program with AssemPro. 

Here is a simple routine that you can use to run one of these commands 
with: 

test: ;(6.5.6B) 

lea diskio,al ;Pointer to I/O structure 

move #13,28(al) ;Pass command (for example, 13) 

move . 1 execbase,a6 JEXEC base address in A6 

jsr SendIO(a6) JCall function 

If CHANGENUM (command 13) is executed, in D7 you'll get the num- 
ber of times a disk was taken out and put in the drive. If you call the 
program, you'll get a value back. If you take the disk out and put it back 
in, the number is two higher the next time you call the program. 

The CHANGESTATE command (command 14) tells whether a disk is in 
the drive or not. If one is, a zero comes back. Otherwise, a $FF is re- 
turned. 

You get the same values back from the PROTSTATUS function (com- 
mand 15). Here a zero means that the disk isn't write protected, while 
$FF means that it is. 

Now let's look at the READ and WRITE functions. These operations 
need a few more parameters than the status functions. You need to pass 
the following parameters: 
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The address of the I/O buffer in the data pointer, the number of bytes to 
be transferred in I/O length, and the data address on the disk in I/O offset. 

The number of data bytes must be a multiple of 512, since every sector is 
512 bytes, and only whole sectors can be read. 

The data address is the number of the first byte in the sector. If you want 
to use the first sector, the offset is zero. For the second sector, it's 512, 
etc... The formula is: 

Offset = ( Sec tor_n umber - 1) * 512 

Here is a routine that loads the first two sectors of the disk into the 
buffer: 



est: (6.5.6C) 


I 






lea 


diskio,al 






move 


#2,28(al) 




jCommand: READ 


move.l 


#diskbuff,40(al) 


;Buf fer 


move.l 


#2*512, 36(al) 




jLength: 2 sectors 


move.l 


#0*512,44 (al) 




;Of fset: sectors 


move.l 


execbase,a6 




JEXEC base address 


jsr 


SendIO(a6) 




JStart function 



Start the program from the debugger and then look at the buffer's contents 
after the program ends. You can find out the format of the disk here. If 
you want to read a sector that's being used, change the in the offset 
definition to 700 and start again. It's highly probable that there's some 
data there. 

To modify and write back the data that you've read from the disk, you 
need command three, the WRITE command. The parameters are the same. 

If you've execute the WRITE command, you're probably wondering why 
the disk light didn't go on. That's because the Amiga writes a track that 
has been read into a buffer of its own. It WRITEs data there as well. It 
won't write the data to disk until another track is accessed. 

You can have the data updated directly as well using command four, the 
UPDATE command. 

Command 11, the FORMAT command, is also quite interesting. This 
command needs a data field that is 11*512=5632 bytes long — the length 
of a track. The offset must be a multiple of this number so that you start 
at the beginning of a track. 

The length must be a multiple of 5632 as a result. If several tracks are 
formatted, each track is filled with the same data. 
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You can use this function to easily write a disk copy program. You 
READ the source disk and then FORMAT the corresponding track on the 
destination disk. That's how the DiskCopy program works — it reformats 
the destination disk. 

Command ten, the SEEK command, just needs the offset. It moves the 
Read/Write head of the drive to the position specified without making a 
disk access or testing if it's at the right position. 

Command 12, the REMOVE command, is used to install an interrupt 
routine that is called when the disk is removed from the disk drive. The 
address of the interrupt structure is passed in the data pointer of the I/O 
structure. If there's a zero here, the interupt routine is turned off. 

Here is a complete example program in AssemPro format: 

; ***** Track disk-Basic function 10/86 S.D. ***** 

ILABEL ASSEMPROlIncludes/amiga.l ;AssemPro only 



;def ined in INIT_AMIGA 



OpenLib 


=-30-378 


closelib 


=-414 


;ExecBase 


= 4 


* calls to 


Amiga Dos : 


Open 


=-30 


Close 


=-30-6 


opendevice 


=-444 


CloseDev 


=-450 


Sendlo 


=-462 


Read 


=-30-12 


Write 


=-30-18 


WaitForCh 


=-30-174 


mode old 


= 1005 


INIT_AMIGA 


run: 




bsr 


init 


bra 


test 



;AssemPro only 



JInitialization 
;System-Test 

init: ;System initialization 

and open 

move.l ExecBase,a6 ;Pointer to EXEC-library 

lea dosname,al 

moveq #0,d0 

jsr openlib(a6) ;Open DOS-Library 

move.l d0,dosbase 

beq error 

lea diskio,al 
move.l #diskrep,14 (al) 
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b P : 



test: 



clr.l 


dO 


clr.l 


dl 


lea 


trddevice,aO 


jsr 


opendevice (a6) 


tst.l 


dO 


bne 


error 



lea consolname (pc) ,al 

move.l #mode_old,dO 

bsr openfile 

beq error 

move.l dO,conhandle 

rts 



bsr 



bsr 
bra 



accdisk 

getchr 
qu 



;Open trackdisk.device 

;Con sole-Definition 
;Console open 



jwait for character 



qu: 



move.l #-l,d7 

move.l ExecBase,a6 lea 

move #9,28 (al) 

move.l #0,36 (al) 

jsr sendio(a6) 

move.l conhandle,dl 

move.l dosbase,a6 

jsr close(a6) 

move.l dosbase,al 

move.l ExecBase,a6 

jsr closelib(a6) 

lea diskio,al 

move.l 32(al),d7 

jsr closedev(a6) 

EXIT AMIGA 



openfile: 

move.l al,dl 

move.l d0,d2 

move.l dosbase,a6 

jsr open{a6) 

tst.l dO 
rts 



scankey: 



;Flag 
diskio,al 

jWindow close 
jDOS.Lib close 



;AssemPro only 

;Open File 

jPointer to the I/O- 

De fin it ion -Text 



move.l conhandle,dl 
move.l #500, d2 



;Test for key 
JWait value 
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move.l dosbase,a6 

jsr waitforch(a6) 

tst.l dO 
rts 



getchr: 



move.l #l,d3 
move.l conhandle,dl 



lea 


inbuf f,al 


move.l 


al,d2 


move.l 


dosbase,a6 


jsr 


read (a6) 


clr.l 


dO 


move.b 


inbuf f,dO 


rts 




accdisk: 




lea 


diskio,al 


move 


#2,28(al) 


move.l 


#diskbuff,40(al) 


move.l 


#2*512, 36(al) 


move.l 


#20*512,44 (al) 


move.l 


ExecBase,a6 jsr 


rts 





JGet one character from 
keyboard 

;l character 

;Buf fer- Address 



JCommand: READ 
;Buf fer 

jLength: 2 Sectors 
;Of fset: n Sectors 
sendio (a6) 



dosname: dc.b ' dos. library ' ,0,0 

align .w 
dosbase: del 

consolname". dc.b 'RAW: 0/100/64 0/100/** Test-Window S.D. 

VO.1',0 
trddevice: dc.b ' trackdisk. device ' ,0 

align.w 
conhandle: del 

inbuf f: ds.b 8 

diskio: ds.l 20,0 

diskrep: ds.l 8,0 

diskbuff: ds.b 512*2,0 



end 
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7 Working with Intuition 



Now that you've learned so much about machine language, let's look at 
the special features of the Amiga. Let's look at the operating system 
Intuition that is in charge of windows, screens, the mouse and lots of 
other things. Before taking a look at these beautiful features, there's some 
bad news. 

First, though, let's hear the good news. Since Intuition has so many 
functions, it allows you to be very creative in programming your ideas. 
The disadvantage is that the flexibility means that you have to use a lot 
of parameters, and that makes for a lot of tedious work. 

However, this is no grounds for a panic. Once you've built up the neces- 
sary routines, the programming and experimentation become increasingly 
interesting. Before you try out new program variations, you should save 
your source code to disk, because Intuition get's fairly upset about bad 
parameters and often responds by crashing the system. 

Now let's get to work. To start working with Intuition, you need the 
Intuition library. You can load it with the OpenLibrary function from the 
EXEC library. Here's the subroutine that takes care of initialization. 

OpenLib = -4 08 
ExecBase = 4 
run: 

bsr openint ;Load Intuition library 

openint: ;* Initialize and open system 

move.l ExecBase,a6 ;EXEC base address 
lea IntName,al ;Name of Intuition 

;library 
jsr OpenLib (a6) ;Open Intuition 
move.l dO,intbase ;Save Intuition base address 
rts 

IntName: dc.b "intuition. library", 
align 

intbase: del ;Base address of 

Jlntuition 

When your program is finished, you need to close the screens, the win- 
dow and the library. To do this, use the CloseLibrary function from the 
EXEC library. It has an offset of -414. Here's the subroutine: 
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CloseLibrary = -414 



closeint: 

move.l execbase,a6 
move.l intbase,al 



;* Close Intuition 
;EXEC base address in A6 
Jlntuition base address 
in Al 

jsr CloseLibrary (a6) ;Close Intuition 

rts ;Done 



Now that you've got that taken care of, you can finally start working 
with Intuition. 
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7.1 Open screen 



Intuition is a graphics operating system. For this reason, you'll be 
working with the screen. It's even more interesting to work with several 
screens at the same time. However, you only have one monitor on the 
Amiga. 

You can open as many screens as you like (at least, as long as there's 
some memory available). You can open a window, display menus and do 
I/O's there. The individual screens are fully independent. You can work 
with all of them simultaneously on the monitor. 

You can move individual screens forward and back to your heart's content. 
You can also press the left <Amiga> key and then an "m" to return to the 
Workbench screen after getting into the different screens. 

You want to begin programming Intuition by setting up a screen. You've 
already loaded the Intuition library, so you can use the OpenScreen func- 
tion. 

Wait a minute! What should the screen look like, where should it go, and 
what form should it have? You need to look at the options for the form of 
the screen you have available. 

The input to the screen is in the form of a table that has 13 entries. Let's 
take a look at the parameters that you need for our screen. 

You'll start the table with the label "screendefs" which must be at an 
even address: 

align 
screen_def si ;* The screen table begins here 

The first bit of information that the screen needs is the position and size. 
Let's have it start in the upper left corner and fill the entire screen. You'll 
use the positions X=0 and Y=0, the width 320 and the height 200. This 
means that your screen is the maximum size. 



x pos: 


dew 





;X-Position 


y pos: 


dew 





;Y-Position 


width: 


dew 


320 


jWidth 


height: 


dew 


200 


jHeight 
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Next you need to decide which colors should be displayed. That depends 
on the number of bit planes, on the depth. Let's choose two. That means 
you have 2 A 2 (4) colors available. If the depth was one, you'd only have 
two colors available. Let's choose two, since four colors is usually 
plently. 

depth: dew 2 JNumber of bit planes 

Next you need to choose the color of the title line and the function sym- 
bols. Give the number of the color register: 

detail_pen: dc.b JColor of the text, etc... 

Now for the color of the text background: 

block_pen: dc.b 1 ;Background color 

Make sure that these two inputs fit in a byte. The colors are normally the 
following (if the standard values haven't been changed). You'll notice that 
the number of colors depends on the number of bit maps. 

Een Color 



Background (blue) 

1 White 
for two bit planes 

2 Black 

3 Red 

for three bit planes 

4 Blue 

5 Violet 

6 Turquoise 

7 White 
for four bit planes 

8 Black 

9 Red 

10 Green 

11 Brown 

12 Blue 

13 Blue 

14 Green 

15 Green 



The next word contains the bits that decribe the appearance of the screen. 
The bits are: 
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Bit 



13 
14 
15 



Value 



Name 



Meaning 



1 


2 


GENLOCK VIDEO 




2 


4 


INTERLACE 


Puts the screen in Interlace 
mode. The resolution and thus 
the maximum screen size are 
doubled. 


6 


$40 


PFBA 




7 


$80 


EXTRA HALFBRITE 


8 


$100 


GENLOCK AUDIO 




10 


$400 


DBLPF 


Divides the screen into a border 


and 






character area 


11 


$800 


HOLDNMODIFY 


Turns on Hold-and-Modify 
mode 



$2000 
$4000 
$8000 



VP_HIDE 
SPRITES 
MODE 640 



Allows sprites to be used 
Turns on the highest resolu- 
tion graphics for the screen 
(640x400) 



Choose the value two (normal) for your example screen: 



view modes: dew 



jRepresentation mode 



The following word is constructed in such a way that each bit has its own 
meaning. Use this to set what sort of screen it is. Choose 15 so the 
screen is a "Custom screen", which allows you all of the options. 



screen_type: dew 



15 



jScreen type: custom screen 



Next there's a pointer to the character set to be used for all output to the 
screen. If you don't want to install your own character set, just put a zero 
here, and the standard character set is used. 



font: 



del 



JCharacter set: Standard 



Next there's a pointer to the text that's used as the name of the screen. 
The text ends with a zero, just like window names must. 



title: 



del name jPointer to title text 



Next comes a long word that defines the gadgets. These gadgets represent 
the functions, like "Bring forward", that can be accessed via a mouse click 
in the screen. The long word in this table is a pointer to a list which 
specifies the gadgets. These aren't the system gadgets. However, you're 
only using system gadgets here, so put a zero here. 



gadgets: 



del 



;No gadgets 
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Finally there's a long word that you only need if you want to use a spe- 
cial bit map just for your screen. Since this isn't the case, just put a zero 
here. 



bitmap: 



del 



;No bit map 



That's it for the list entries that you need to define the screen. You still 
need the text for the name of the screen. Enter the following: 

sname: dc.b 'Our Screen ' ,0 ;Screen title 

Here's a quick overview of the list: 



align 








screen defs: 






;* The screen ta 


x pos: 


dew 





;X-Position 


y pos: 


dew 





;Y-Position 


width: 


dew 


320 


jWidth 


height: 


dew 


200 


;Height 


depth: 


dew 


2 


;Number of bit planes 


detail_pen: 


deb 





;Color of the text, etc... 


block pen: 


deb 


1 


jBackground color 


view modes: 


dew 


2 


jRepressentation mode 


screen type: 


dew 


15 


JScreen type: custom 
Jscreen 


font: 


del 





;Character set: Standard 


title: 


del 


sname ;Pointer to title text 


gadgets: 


del 





;No gadgets 


bitmap: 


del 





;No bit map 


sname: 


deb 


'Our 


Screen ',0 ;Screen title 



Once you've decided on the parameters, it's very easy to open the screen. 
You need Intuition's OpenScreen function. It's offset is -198, and it only 
needs one parameter, the address of the parameter table. The program frag- 
ment looks like this: 



OpenScreen = - 


198 






bsr 


openint 




;Open Intuition 


bsr 


scropen 




;Open screen 


scropen: 






;* Open screen 


move.l 


intbase,a6 




JIntuition base address 
Jin A6 


lea 


screen defs 


,a0 


jPointer to table 


jsr 


openscreen ( 


a6) 


;And open 


move.l 


dO.screenhd 




;Save screen handle 


rts 






jReturn to main program 



screen defs: 



;Table info follows 



Now the Amiga's Workbench screen is covered by your screen. Now you 
can do what you want with it until the program is done. Afterwards, the 
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screen must be closed again, so that you can see the Workbench screen 
again. 

Use the CloseScreen function (offset -66) to do this. The only parameter 
it needs is the pointer to the screen structure you got back from the Open- 
Screen function. 

CloseScreen = -66 

scrclose: ;*Close screen 

move.l intbase,a6 Jlntuition base address 

Jin A6 
move.l screenhd,aO jScreen handle in AO 

jsr CloseScreen (a6) jClose screen 

rts ;Done 

The long word that OpenScreen returned to you is a pointer to a screen 
structure that contains all the needed data about the screen. Besides the 
data which was given, there is a pointer in the screen area for individual 
bit planes, etc... 

The form of this structure is fairly complicated and contains some data 
that you can't use. Several of the parameters are interesting, however. 
Here's a selection of the usable parameters: 

No. Name Function 






(NextScreen.L) 


Pointer to next screen 


4 


(FirstWindow) 


Pointer to first window struct 


8 


(LeftEdge.W) 




$A 


(TopEdge.W) 


Position of the screen 


$C 


(Width.W) 


Width 


$E 


(Height. W) 


Height 


$10 


(MouseY.W) 




$12 


(MouseX.W) 


Mouse position in the screen 


$14 


(Flags.W) 


Screen flags 


$16 


(TitlcL) 


Pointer to title text 


$1A 


(DefaultTitle) 


Pointer to normal title 


$28 


(FontL) 


Pointer to character set 


SCO 


(PlaneCL) 


Pointer to the bit plane 


$C4 


(PlaneLL) 


Pointer to the bit plane 1 


$C8 


(Plane2.L) 


Pointer to the bit plane 2 


$cc 


(Plane3.L) 


Pointer to the bit plane 3 



An example of an application for the plane pointer is writing and using 
your own character routine. Next you want to move the address of a plane 
into an address register as follows: 

move.l screenhd,a5 ;Screen pointer in A5 
move.l $c0(a5),a5 ;Bit plane 0-pointer in A5 
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If you want to try this, do the following: 



move.l screenhd,a5 



lopl: 



move.l 


$c0 (a5) ; 


,a5 


move 


#$20,d0 




move 


d0,(a5) 




add.l 


#80,a5 




dbra 


dO.lopl 





;Screen pointer in A5 
;Bit plane 0-pointer in A5 
jCounter D0 = $20 



;Write counter bits in picture 
;Address +80, next line 
;Continue until D0<0 



This program draws a white, square pattern that corresponds to the bit 
pattern for the numbers $20 to 0. This isn't a particularly useful program, 
but it shows how easy it is to write from a machine language program 
directly to the screen. If you change the offset in the second line to $C4, 
the pattern is read. 

You can move the entire screen with the normal technique of moving the 
mouse pointer into the upper border and moving it up and down with the 
left mouse key depressed. You can do the same thing with a program. 

Let's move the screen without the mouse. Use the joystick for demonstra- 
tion purposes. Put the joystick in port two. As you saw in the chapter on 
the hardware register, you can read memory location $DFF00C to find in- 
formation about the joystick. You can find the direction the screen should 
be moved here. 

Moving the screen requires another Intuition function. You use the Move- 
Screen function which has an offset of -162 and needs three parameters to 
do this. The parameters are: 

In A0 the pointer to the screen structure that you got back in DO when 

you opened the screen. (You saved it in "screenhd".) 
In Dl the desired movement in the Y-direction, the vertical direction 
In DO the horizontal movement in the X-direction. The variant doesn't 
work so you can only move the screen vertically. 



Insert the following lines in your program: 



MoveScreen 


=-162 


scrmove: 




move.l 


intbase,a6 


move.l 


screenhd,aO 


clr.l 


dO 


jsr 


MoveScreen ( 


rts 





;* Move screen DO to the right 

; and Dl down 

JIntuition base address in A6 

jScreen handle in A0 

;No horizontal movement 

;Move screen 

;Done 
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Now your looking at a complete program that goes through the following 
steps: 

1 . Opens the Intuition library 

2. Opens a screen. 

3. Moves the screen in the direction specified by the joystick in 
port two. 

4. Closes the screen when the fire button is hit. 

5. Closes the Intuition library. 

6. Ends. 

Here is the complete program including the subroutines, so you'll have it 
all in one spot: 



;** Demo progr 

MoveScreen 

OpenScreen 

CloseScreen 

CloseLibrary 

OpenLib 

ExecBase 

joy2 

fire 

run: 



loop: 



noup: 



ende: 



amm to open and move a screens * * 
= -162 
= -198 
= -66 
= -414 
= -408 
= 4 

= $df f 00c 
= $bfe001 



bsr 
bsr 
move 

tst.b 

bpl 

move 

sub 

cmp 

bne 

move.l 

bsr 

bra 

cmp 

bne 

move.l 

bsr 

bra 

bsr 
bsr 

rts 
openint: 

move.l 

lea 

jsr 

move.l 

rts 



openint 
scropen 
joy2,d6 

fire 

ende 

joy2,d0 

d6,d0 

#$0100,d0 

noup 

#-l,dl 

scrmove 

loop 

#$0001,d0 

loop 

#l,dl 

scrmove 

loop 

scrclose 

closeint 



ExecBase, a6 

IntName,al 
OpenLib (a6) 
dO,intbase 



;Open library 
;EXEC base address 
;Joystick 2 Data 
;Fire button 2: Bit 7 



;Open Intuition 

;Open screen 

;Save joystick info 

JTest fire button 
jPressed down: done 
jBasic info in DO 
;Subtract new data 
;u P ? 
;no 

;dy=-l direction y 
jMove up 



;Down ? 
;No 
;dy = l 
JMove down 



;Close screen 

;Close Intuition 

;Done ! 

;* Initialize and open system 

;EXEC base address 

;Name of Intuition library 

;Open Intuition 

;Save Intuition base address 
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closeint: 

move.l 
move.l 
jsr 
rts 

scropen: 

move.l 

lea 

jsr 

move.l 

rts 

scrclose: 

move.l 
move.l 
jsr 
rts 

scrmove: 

move.l 

move.l 

clr.l 

jsr 

rts 

Align 

screen defs: 

xpos: 

y_pos: 

width: 

height: 

depth: 

detail_pen: 

block_pen: 

view_modes: 

screen_type: 

font: 

title: 

gadgets: 

bitmap: 

intbase: 

screenhd: 

IntName: 

align 

sname: 

align 
end 



execbase,a6 

intbase, al 
CloseLibrary (a6) 



intbase, a6 
screen_def s,aO 
openscreen (a6) 
dO, screenhd 



intbase, a6 
screenhd,aO 
CloseScreen (a6) 



intbase, a6 

screenhd,aO 

dO 

MoveScreen (a6) 



dew 
dew 
dew 
dew 
dew 
deb 
deb 
dew 
dew 
del 
del 
del 
del 
del 

del 
deb 

deb 



;* Close Intuition 

JEXEC base address in A6 

JIntuition base address in Al 

;Close Intuition 

JDone 

;* Open screen 

JIntuition base address in A6 

JPointer to table 

;Open 

;Save screen handle 

jReturn to main program 

J* Close Screen 

JIntuition base address in A6 

JScreen handle in AO 

JClose screen 

JDone 

;Move screen DO right/Dl down 

JIntuition base address in A6 

jScreen handle in AO 

;No horizontal movement 

jAnd move 

JDone 



;* Screen table begins here 
;X-position 

;Y-position 
320 ;Width 

200 jHeight 

2 JNumber of bit planes 

1 ;Text color = white 

3 JBackground color = red 

2 JRepressentation mode 

15 JScreen type: Custom screen 

jStandard character set 

sname JPointer to title text 

;No gadgets 

;No bit map 

jBase address of 

Intuition 
JScreen handle 

' intuit ion. library ',0 

'Our Screen ' ,0 JScreen title 



From this example, you can see how easy scrolling actually is. Another 
easy thing to do is to use the DisplayBeep function. It has offset -96; the 
only parameter it needs is the screen pointer that you stored in the 
"screenhd" memory block. This function covers the screen with an orange 
color for a short while. The screen isn't changed. The beep function can 
be used as follows: 
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DisplayBeep = -96 

move.l intbase,a6 ;intuition base address in A6 
move.l screenhd,aO jScreen pointer in AO 
jsr DisplayBeep (a6) ;Light up screen 

If you put a zero instead of a screen pointer in AO, the whole screen 
blinks. 

Good, now you have your own screen that you can move up and down. 
What good is it if you can't put anything on it? Let's open a window on 
the screen! 
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7.2 Open window 



As you saw in the chapter on program initialization, it's easy to open a 
window with the DOS library. You can't use this method on your own 
screen however. You need to use another method that can open any win- 
dow on any screen. 

Intuition has a function called Open Window which handles this sort of 
work. It has an offset of -204 and needs only one parameter, a pointer to a 
window definition table. This pointer goes in register A0. 

This table is very similar to the one used to define the screen. The first 
four values specify the X- and Y-positions, the width, and the height of 
the window to be opened. Here's an example: 



align 






indow defs: 






dew 


10 


;X-position 


dew 


20 


;Y-position 


dew 


300 


JWidth 


dew 


150 


JHeight 



Next come two bytes that define the color of the letters and the back- 
ground: 

deb 1 ;White letter color 

deb 3 ;On a red background 

The next long words contain the IDCMP flag in its bits. The bits deter- 
mine the circumstances under which Intuition sends a message to the 
program. The bits have the following meaning: 
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Bit 


Value 


Name 


Meaning (Report if) 





$000001 


SIZEVERIFY 




1 


$000002 


NEWSIZE 


Window size changed 


2 


$000004 


REFRESHWINDOW 




3 


$000008 


MOUSEBUTTONS 


Mouse key hit 


4 


$000010 


MOUSEMOVE 


Mouse moved 


5 


$000020 


GADGETDOWN 


A special gadget chosen 


6 


$000040 


GADGETUP 


Same as above 


7 


$000080 


REQSET 




8 


$000100 


MENUPICK 


A menu item chosen 


9 


$000200 


CLOSEWINDOW 


A window closed 


10 


$000400 


RAWKEY 


A key pressed 


11 


$000800 


REQVERIFY 




12 


$001000 


REQCLEAR 




13 


$002000 


MENUVERIFY 




14 


$004000 


NEWPREFS 


Preferences modified 


15 


$008000 


DISKINSERTED 


A disk put in 


16 


$010000 


DISKREMOVED 


A disk taken out 


17 


$020000 


WBENCHMESSAGE 




18 


$040000 


ACTIVEWINDOW 


A window activated 


19 


$080000 


INACTIVEWINDOW 


A window deactivated 


20 


$100000 


DELTAMOVE 


Report relative mouse move- 
ment 



If you want your first window to respond only by clicking on the close 
symbol, write the following: 



del 



$200 JIDCMP flags: CLOSEWINDOW 



Next comes a long word whose bits determine the window's type. You 
can use this to construct a window to your exact specifications. This is 
quite different from windows opened with the DOS function. The bits 
mean: 
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Bit 


Value 


Name 


Meaning (Report if) 





$0000001 


WINDOWS I ZING 


Window size is changeable 


1 


$0000002 


WINDOWDRAG 


Window is moveable 


2 


$0000004 


WINDOWDEPTH 


Window covering is possible 


3 


$0000008 


WINDOWCLOSE 


Window close symbol 


4 


$0000010 


SIZEBRIGHT 




5 


$0000020 


SIZEBBOTTOM 




6 


$0000040 


SIMPLE REFRESH 


New drawing manual 


7 


$0000080 


SUPER_BITMAP 


Save the window's contents 


8 


$0000100 


BACKDROP 


Move window back 


9 


$0000200 


REPORTMOUSE 


Report mouse coordinates 


10 


$0000400 


GIMMEZEROZERO 




11 


$0000800 


BORDERLESS 


Window without border 


12 


$0001000 


ACTIVATE 


Window active 


13 


$0002000 


WINDOWACTIVE 




14 


$0004000 


INREQUEST 




15 


$0008000 


MENUS TATE 




16 


$0010000 


RMBTRAP 


Right mouse key: no menu 


17 


$0020000 


NOCAREREFRESH 


No refresh message 


24 


$1000000 


WINDOWREFRESH 




25 


$2000000 


WBENCHWINDOW 





To refresh is to rebuild the window contents when necessary, for instance 
when the window's size is changed. If none of the refresh bits are set, 
you're in Smart-Refresh-Mode. In this case, Intuition takes care of re- 
freshing the window. This is the easiest method. 

If you choose the value $100F as the type for your example window, the 
window is active once it's opened, and it has all the system gadgets: 



del 



$100f JACTIVATE and all gadgets 



The next long word in the list allows you to use your own gadgets in the 
window. This long word is a pointer to the structure of a your gadget. 
Since you don't want this, just put a zero here. 



del 



;First gadget:no gadgets of our own 



The next long word is a pointer to a graphics structure so you can design 
your own symbol for checking menu points. Put a zero here. You'll use 
the standard sign: 



del 



;CheckMark: Standard 



The next list entry is a pointer to the text for the window name. This text 
must be closed by a null byte. 



del 



windowname 



jPointer to window name 
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The next long word is a pointer to the screen structure that you got back 
after calling the OpenScreen function. The easiest way to do this is to 
save the pointer to this location in the buffer: 

screenhd: del ;Screen pointer 

The next long word is a pointer to a bit map if you want one of your own 
for the window. Since you don't want one, put a zero here: 

del ;No bitmap of our own 

Next come four values that set the maximum and minimum width and 
height of the window: 

dew 150 JSmallest width 

dew 50 JSmallest height 

dew 320 JMaximum width 

dew 200 JMaximum height 

The last value in the list is the screen type of the screen the window is 
located in. Put a 15 here. You're using our screen as a Custom screen: 

dew 15 JScreen type: custom screen 

Here's a quick overview of the whole list: 



;X-position 

;Y-position 

JWidth 

jHeight 

jWhite print color 

;On a red background 

;IDCMP flags: CLOSEWINDOW 

JACTIVATE and all gadgets 

;First gadget: no gadgets 

;of our own 

;CheckMark: Standard 

;Pointer to window name 

JScreen pointer 

;No bitmap of our own 

JSmallest width 

JSmallest height 

jMaximum width 

jMaximum height 

JScreen type: custom 

Jscreen 

;And here comes the window name: 

windowname: dc.b 'Our Window', 
align 
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align 






window defs". 








dew 


10 




dew 


20 




dew 


300 




dew 


150 




deb 


1 




deb 


3 




del 


$200 




del 


$100f 




del 







del 







del 


windowname 


screenhd: 


del 







del 







dew 


150 




dew 


50 




dew 


320 




dew 


200 




dew 
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Insert these lines in the program you listed above. Here are the two sub- 
routines for opening and closing the window: 



OpenWindow = -204 
CloseWindow = -72 



windopen: 






move.l 


intbase,a6 


JIntuition base address in A6 


lea 


windowdef,aO 


jPointer to window definition 


jsr 


openwindow(a6) 


;Open window 


move.l 


dO,windowhd 


;Save window handle 


rts 






windclose: 






move.l 


intbase,a6 


JIntuition base address in A6 


move.l 


windowhd,aO 


jWindow handle 


jsr 


closewindow (a6) 


JClose window 


rts 






windowhd: 


del 


jWindow handle 



Now you can insert a "bsr windowopen" after the "bsr scropen" and a "bsr 
windclose" before the "bsr scrclose" command. Once you've started the 
program, move the window around in the screen. You'll find that you 
can't move the window out of the screen with the mouse. 

The window in the example has the close gadget in the upper left corner. 
Normally if you click it, the window is closed. Try clicking it. You'll 
find that nothing happens. 

The display of this and all other gadgets, as well as other events must be 
programmed in, since Intuition doesn't know which action causes which 
event. We'll take a look at how to handle this in the next chapter. 
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7.3 Requesters 



If you only have one disk drive, you've certainly seen the Amiga mes- 
sage, "Please insert xxx in unit 0", a lot. This window is another window 
that has two fields for clicking. This sort of message with a choice of 
options is called a requester. 

You want to take a look at how to program a requester. First, you need a 
window for the requester to appear in. You opened a window of this sort 
in the example program. 

To display a requester, use the Intuition function AutoRequest (offset - 
348). It takes care of drawing and managing the requester. This function 
needs the following parameters: 

In A0 The pointer to the window structure that you put in "windowhd" 
In Al A pointer to the text structure that should stand over the choice 

buttons 
In A2 Same as above for the text of the left button. 
In A3 Same as above for the right button. 
In DO The IDCMP flag which lets you know what event should go 

with the clicking of the left button 
In Dl Same as above for the right button. 
In D2 The width of the whole requester. 
In D3 The height of the requester. 



Insert the following lines in your program: 



AutoRequest = -348 



request: 




move.l 


windowhd,aO 


lea 


btext.al 


lea 


ltext,a2 


lea 


rtext,a3 


move.l 


#0,d0 


move.l 


#0,dl 


move.l 


#180,d2 


move.l 


#80,d3 


move.l 


intbase,a6 


jsr 


autorequest (a6 


rts 





jPointer to window structure 

;Pointer to text structure 

jLeft activates by clicking 

;Right activates by 

clicking 

;Width and 

;Height of the Requester 

Jlntuition base address 

;Display Requester 



179 



7. Working with Intuition Amiga Machine Language 



The flags passed in DO and Dl offer some interesting possibilities. The 
system messages that tells you to enter a particular disk are overlooked 
when the DISKINSERTED flag is similar. Putting a disk in brings about 
the same responce as clicking the "Retry" button. 

What's new is the use of a text structure. Use three of them. Text struc- 
tures are lists that contain entries for the text that you need. 

These lists begin with two bytes that are used to define the color. The 
first byte is the color of the text. The second is for the background color. 
Here this doesn't have any meaning. 

btext: 

dc.b 2 ;Black text color 
dc.b ;Background color 

The next byte specifies the character mode. A zero means that the text is 
output normally. A four means the text is output inverted. 

dc.b ;Normal text representation 

The next entries are words. For this reason the addresses must be even, so 
you need to either insert another byte or use the "align" pseudo-op. The 
following words are the X- and Y-position of the text relative to the upper 
left corner of requester. 

dew 10 ;X-position 

dew 5 ;Y-position relative to upper corner 

Next, there's a pointer to the character set that is used. Put a zero here to 
use the standard set 

del jStandard character set 

Next you need to give the address of the text that should be output. This 
text must be closed with a null byte. 

del text ;Pointer to text 

You need a long word at the end of the list that is either a pointer to 
another text or a zero if no more text is needed. 

del ;No more text 

Here are the three text structures that you need for the example: 
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btext: 




JText structure for the title 




dc.b 0,1 


jColor 




dc.b 


jMode 




align 






dew 10,10 


JText position 




del 


jStandard font 




del bodytxt 


jPointer to text 




del 


;No more text 


bodytxt: 


deb "Requester 
align 


Text",0 


ltext 


;Text 


structure of the left button 




deb 0,1 


;Color 




deb 


JMode 




align 






dew 5,3 


JText position 




del 


JStandard font 




del lefttext 


JPointer to text 




del 


;No more text 


lefttext: 


deb "left",0 
align 




rtext: 








deb 0,1 


JColor 




deb 


;Mode 




align 






dew 5,3 


JText position 




del 


JStandard font 




del righttext 


JPointer to text 




del 


;No more text 


righttext: 


dc.b "right", 
align 





After calling the requester, DO contains the information about which of 
the buttons were pressed, and in which button the event took place. If DO 
is zero, it was the right button. If it is one, it was the left button. 
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7.4 Event handling 



Pretend you've opened a window that has the close symbol, and you want 
the program to react to this symbol being clicked. You need a signal from 
Intuition that lets you know that an event has taken place. This signal is 
called a message. 

The EDCMP flag of the window specifies which events should cause 
Intuition to send a message. By setting the bits for WENDOWCLOSE, 
you can allow a message to be sent when the close symbol is clicked. 

To get the message, you can use the EXEC function GetMsg (offset - 
372). It needs the source address of the event as a parameter. Here the 
source is the User port (which doesn't have anything to do with the User 
port on old Commodore computers). 

The user port contains a table which has entries which specify the events 
that have taken place and related things like mouse position and time. 

How do you find the User port? Use the pointer to the window structure 
that you got back from the Open Window function and stored in the 
"windowhd" memory block. 

This pointer points to the window structure of this window. This struc- 
ture consists of a number of entries. Some are copies of the parameters 
from our window definition table. We won't cover all the entries, because 
most won't be interesting to you. You're more interested in the pointer to 
the user port. It's in the window structure. 

You can find this in the long word that begins in the 86th byte of the 
structure. You can get this long word with the following lines of code: 

move.l windowhd,aO jPointer to structure in AO 

move.l 86(a0),a0 ;User port pointer in AO 

You can call the GetMsg function with this pointer in AO by using the 
following lines of code in your program: 
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GetMsg = -372 

move.l windowhd,aO jPointer to structure in AO 

move.l 86(a0),a0 ;User port pointer in AO 

move.l ExecBase,a6 ;EXEC base address in A6 

jsr GetMsg (a6) ;Get message 

This function returns a value in the DO register. This value is a pointer to 
another structure, the Intuition Message Structure. If there's a zero in DO, 
no event has taken place. 

The long word that starts at the 20th byte in this structure contains the 
information about which event took place. Evaluating the information is 
easy, since the bits of this long word have the same meaning as the 
IDCMP flag that you described when you looked at opening windows. 

Put the lines above after "loop" and then insert the following: 

move.l d0,a0 jMessage pointer in AO 

move.l 20(a0),d6 ;Save event in D6 

tst.l dO ;Did an event take place? 

bne end ;Yes ! 

Now you can end this program by clicking the close symbol. This way 
you can find out if an event has taken place. You can use D6 to determine 
what event took place. In the example, D6 contains the number 
$00000200, which means that the close symbol was clicked. 

To see if this works with other events, change the $200 IDCMP flag to 
$10200 in the window definition table. When you've assembled and 
started this version, take the disk out of the drive — the program termin- 
ates. 

The IDCMP flags that you've got now cause the clicking of the close 
symbol and the taking out of the disk (DISKREMOVED) to be reported. 
If you want to find out which of the events took place, you can look in 
D6. It has a $200 in it if the window was closed, a $10000 if the disk 
was removed. 



183 



7. Working with Intuition Amiga Machine Language 



7.5 Menu programming 



Now let's look at one of Intuition's more interesting capabilities: menu 
programming. By using menus, you can make your programs extremely 
user-friendly. 

There are a lot of ways for you to use menus. You can make menu points 
unusable, output submenus, choose the type of menu entries (allow text 
or pictures to be output), etc... To have lots of options, you need some 
parameters. 

Let's produce a menu with the SetMenuStrip function (offset -264) of 
Intuition. The function only needs two parameters, a pointer to the menu 
structure of the window to be drawn and a pointer to the window structure 
of the window in which the menu is to function. Each window can have 
its own menu that is active when the window is activated. 

Here's the subroutine to set up the menu: 

SetMenuStrip = -264 

setmenu: ;* Initialize a menu 

move.l intbase,a6 Jlntuition base address in A6 

move.l windowhd,aO jPointer to window structure 

lea menu,al ;Pointer to menu structure 

jsr SetMenuStrip (a6) ;Call function 
rts 

Here's a routine to erase the menu: 

ClearMenuStrip = -54 

clearmenu: 

move.l intbase,a6 JIntuition base address in A6 

move.l windowhd,aO JPointer to window structure 

jsr ClearMenuStrip (a6) 

rts 

You've already got the pointer to the window structure. Let's look at the 
menu structure you need for the menu. You need to build a structure like 
this for each menu — for each menu title that appears when you press the 
right mouse key. 

This structure is a table with the following form: 
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First there is a long word that points to the menu structure of the next 
menu. If the current menu is the last one, a zero goes here. 

align 
menu.' 

del menul JPointer to the next menu 

Next come two words which contain the X- and Y-position of the menu 
title: 

dew 20 ;X-position 

dew ;Y-position 

Next, use two words to store the menu title's width and height in pixels: 

dew 50 jWidth 

dew 10 jHeight of menu title 

The next word contains the flag bit that determines whether the menu is 
available or not. An unavailable menu either has gray entries or they are 
drawn weakly. If the flag bit, bit 0, is set the menu is available. Other- 
wise, it is not 

dew 1 ;Menu available 

Now comes a long word which functions as a pointer to the text which is 
used as the menu title. Make sure that the length isn't larger than the 
width entry allows! Otherwise unpleasant things will happen. 

del menutext jPointer to title text 

Next comes a long word which functions as a pointer to the structure of 
the first menu entry of this menu. Each menu entry needs its own struc- 
ture. 

del menuitemOl jPointer to the first menu item 

The last entries in the table are four words that are reserved for internal 
functions. They must be here. 

dew 0,0,0,0 JReserved words 

That's the structure of the first menu. This structure's first long word 
points to the next structure which has the same form. The pointer is set 
to zero in the last menu. 

You still need the structure of the menu entries. These structure tables 
have the following form: 
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They start with a pointer to the next menu item. This pointer is set to 
zero for the last entry. 



align 
menuitemOl: 
del 



menuitem02 



JPointer to next menu item 



Next come four words: the X- and Y -position, the width, and the height 
of the box the menu entry goes in. The size becomes obvious when the 
item is chosen by having the right mouse key clicked on it. Then the box 
becomes visible. As you can see, the next word is determined in the flags. 
First let's set the position and size of the menu point, though: 



dew 





;X-position of an entry 


dew 





;Y-position 


dew 


90 


;Width in pixels 


dew 


10 


jHeight in pixels 



The position entries are relative to the upper left corner of the menu that 
is pulled down. 

The following word was described above: it contains flags for entries to 
this menu item. There are several interesting variations possible. The fol- 
lowing flag bits are contained in this word: 



Bit 


Value 


Name 


Meaning when set 





$0001 


CHECKIT 


Point is checked when chosen 


1 


$0002 


ITEMTEXT 


Text menu item 


2 


$0004 


COMMSEQ 


Choice can be made with keys as well 


3 


$0008 


MENUTOGGLE 


Check turned on and off 


4 


$0010 


ITEMENABLED 


Menu item available 


6 


$0040 


HIGHCOMP 


Item inverted when chosen 


7 


$0080 


HIGHBOX 


Item framed when chosen 


8 


$0100 


CHECKED 


Item is checked 



Here's a description of the bits: 

CHECKIT If this bit is set, a check or a user-defined drawing is put 

in front of the text when the item is chosen. The text 
should begin with two blanks. 

ITEMTEXT The menu item is a normal text if this bit is set. Other- 
wise a drawing is output. 

COMSEQ By setting this bit and entering a character, this menu 

point can be chosen by pressing the right <Amiga> key 
and the key that was input. The input character is then 
displayed in the menu with the Amiga symbol. There 
needs to be space available for this. 
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MENUTOGGLE If this bit is set and checking is allowed (bit 0), the 
second time this point is chosen the check is erased, 
the next time it is displayed again, etc... 

ITEMENABLED Erasing this bit makes the menu item unavailable. 

HIGHCOMP If this bit is set, the box you've defined is inverted 

when this menu item is chosen by the mouse 
pointer. 

HIGHBOX In this mode, the box is framed when it is chosen. 

The two previous bits determine the mode of the chosen menu item. The 
following combinations are possible: 

HIGHIMAGE If both bits are cleared, choosing the bit causes a self- 

defined drawing to be output 

HIGHNONE When both bits are set, there isn't any reaction to 

choosing this item. 

CHECKED This bit can be set by either the program or Intuition. 

It lets you know if the menu text has a check next to 
it or not. You can use this to find out if the item was 
checked by testing bit eight. If it's set, the item was 
checked. You can also use it to cause the item to be 
checked. 

You're chosing the mode CHECKIT, ITEMTEXT, COMMSEQ, MENU- 
TOGGLE, ITEMENABLED and HIGHBOX for the example: 

dew %10011111 ;Mode flag 

Let's get back to the structure of the menu items. After the flag word, 
there is a long word whose flag bits determine whether this menu point 
can turn off another one. Set this to zero: 

del ;No connection 

Now comes the pointer to the structure of the text that should be 
displayed. If the ITEMTEXT bit isn't set, this pointer must point to the 
structure of a drawing. If nothing should be shown, you can set this to 
zero. Use a text in the example and write the following: 

del menuOltext jPointer to menu text structure 
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The following long word only has a meaning if the HIGHEMAGE flag is 
set. Then this long word points to the text or the drawing that should be 
displayed when the menu item's box is clicked. Otherwise the long word 
is ignored, so insert a zero: 

del ;No drawing when clicked 

The next entry is a byte that is used for input of keyboard characters, 
which together with the right <Amiga> key can be used to choose the 
menu item. This only works if the COMMSEQ bit is set. Place a charac- 
ter here: 

dc.b 'A' ;Choose item using <AMIGA>/ 'A' 

Since the next item is a long word, you need an "align" pseudo-op here. 
Next comes the long word that points to the menu item structure of a 
submenu. The submenu is automatically shown when this menu item is 
clicked. You can't nest them any deeper, however, so this long word is 
ignored for submenus. 

If you don't want a submenu to this item, put a zero here: 

align 

del ;No submenu 

The next and final long word is written to by Intuition if you choose 
several menu items. In this case, the menu number of the next menu item 
chosen goes here. 

del preparation 

That's the structure for a menu item. You still need the text structure for 
the text of the item. This isn't complicated, but it makes you get into 
fine details about the form of the menu. You've already learned about this 
text structure when you looked at requesters, so we'll skip an explanation. 

Here is the complete structure of an example menu. You can use two 
menus, each with two subpoints. The second menu point of the left menu 
has a submenu with two entries. You ought to type this program in, so 
that you can experiment with it. You can also use this example to eval- 
uate the clicked menu item. 
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;** Complete menu structure 


menu: 


del menul 


dew 10,30 


dew 50,10 


dew 1 


del menuname 


del menuitemOl 


dew 0,0,0,0 


menuname: 


deb "Menu 1",0 


align 


menul: 


del 


dew 80,0 


dew 50,10 


dew 1 


del menunamel 


del menuitemll 


dew 0,0,0,0 


menunamel: 


deb "Menu 2",0 


align 


menuitemOl: 


del menuitem02 


dew 0,0 


dew 130,12 


dew $9f 


del 


del textOl 


del 


deb "1" 


align 


del 


dew 


textOl: 


deb 0,1 


deb 


align 


dew 5,3 


del 


del textOltxt 


del 


textOltxt: 


deb " Point 0.1", 


align 


menuitem02: 


del 


dew 0,10 


dew 130,12 


dew $57 


del 


del text02 


del 


deb "2" 


align 



for example menu* 
;No next menu 

;x/y 

jWidth/Height 
;Menu enabled 
;Menu title 
JMenu entry 



jFirst menu name 



;No further menu 
;See above 



JSecond menu name 

JFirst menu item 
;Pointer to next entry 

;x,y 

;Width, Height 

;Flags 

JExclude 

;Pointer to text structure 

;Select fill 

;Command 

JSubitem: none 
;Next select: no 

jColors 

*,Mode: overwrite 

;X/Y position 
;Standard character set 
;Pointer to text 
;No more text 



jSecond menu item 



;Activate with <Amiga>/ ' 2 ' 
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del 

dew 
text02: 

dc.b 0,1 

dc.b 
align 

dew 5,3 

del 

del text02txt 

del 
text02txt: 

deb " Point 0.2",0 
align 
menuitemli: jFirst menu point of the 2nd menu 

del menuiteml2 JPointer to second menu point 

dew 0,0 

dew 90, 12 

dew $52 

del 

del textll 

del 

deb 
align 

del 

dew 
textll: 

dc.b 0,1 

deb 
align 

dew 5,3 

del 

del textlltxt 

del 
textlltxt: 

dc.b "Point 1.1", 
align 
menuiteml2: jSecond menu item of second menu 

del ;No more items 

dew 0,10 

dew 90,12 

dew $92 

del 

del textl2 

del 

deb 
align 

del submenuO ;Pointer to submenu 

dew 
textl2: 

deb 0,1 

deb 
align 

dew 5,3 

del 

del textl2txt 

del 
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textl2txt: 

dc.b "Point 1.2",0 
align 
submenuO*. ;First point of submenu 

del submenul ;Pointer to next point 

dew 80,5 

dew 90,12 

dew $52 

del 

del textsO 

del 

deb 
align 

del 

dew 
text s0: 

dc.b 0,1 

deb 
align 

dew 5,3 

del 0,textsOtxt,0 
textsOtxt: 

deb "S Point 1",0 
align 
submenul: jSubmenu, second item 

del 

dew 80,15 

dew 90,12 

dew $52 

del 

del textsl 

del 

deb 
align 

del 

dew 
textsl: 

deb 0,1 

deb 
align 

dew 5, 3 

del 

del textsltxt 

del 
textsltxt: 

deb "S Point 2",0 
align 

The menu items in this example have the following properties as a result 
of their flags: 

Menu 1 The first item, "Point 0.1", can be chosen using the right <Amiga> key 

and the "1" key. This point alternates between checked and not checked, 
which can easily be used to check out the key function. If the item is 
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checked and you hit both keys, the check disappears and vice versa. The 
box at this point is framed when the mouse pointer clicks on it. 

The second item, "Point 0.2" can be chosen using the right < Amiga> key 
and the "2" key. This item is checked the first time it is chosen. 
However, in contrast to the item above, it can't be erased. The box of this 
item is inverted when clicked. 

Menu 2 These two points can't be chosen using keys. The box of the upper item 

is inverted when clicked on; the lower one is framed. When you click the 
second item, "Point 1.2", a submenu with two entries is displayed. 

Experiment with this structure a little bit. Change some values and see 
what happens. As you can see, menu programming isn't as bad as you 
thought, and it offers a lot of options (but you'll have to do lots of 
typing!). 

When you're done experimenting, you'll want to produce your own pro- 
gram with menus. How does the program find whether a menu item in a 
menu has been clicked on? 

You already looked at one way to find out the menu state. You can test 
the CHECKED bit in the flag word of a menu item. If this is set, the 
user clicked on this item with the mouse. 

This only works if checking is allowed for the item being tested. You 
could allow all the menu items to be checked, but this still isn't a good 
solution — it requires testing all the flag bits of all the menus one after the 
other. That makes for very boring programming. 

You've already learned about finding about events from Intuition. You've 
moved the message about which event took place into D6, and you can 
look at it to find out what happened. 

If you set the the eighth bit, the MENUPICK bit, of the IDCMP flag 
long word in the window definition, the choice of a menu point is re- 
ported. Put the following lines in your loop in the main program. 



loop: 



move.l 


execbase,a6 


move.l 


windowhd,aO 


move.l 


86(a0),a0 


jsr 


GetMsg(a6) 


tst.l 


dO 


beq 


loop 


move.l 


d0,a0 


move.l 


$14 (a0),d6 



JEXEC base address in A6 
jWindow structure pointer 
;User point pointer in A0 
;Get message 
;What happened? 
JNothing happened 
jMessage pointer in A0 
JEvent in D6 
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If the program makes it out of the loop, an event has taken place. You 
have the event's flag in the D6 register. You can evaluate the event using 
CMP or BTST to find out which flag bits are set. You can then execute 
the function corresponding to the set bit. You can use lines like the fol- 
lowing ones: 



cmp 
beq 



#$200,d6 
ende 



JWINDOWCLOSE? 
;Yes: program end 



These lines terminate the program when the window is closed. 

If the user chose a menu item, there is a $100 in the D6 register. You 
now need to determine which item it was. 

You can find this information in a word that comes right after the long 
word with the event flags in the message structure. Write: 

move $18(a0),d7 

You now have the code for the clicked menu item in the D7 register. If 
the user just pressed the right key and let it go without choosing a menu 
item, you'll find a $FFFF here. This word doesn't contain just one, but 
three pieces of information: 

Which menu was the item chosen from? 
Which menu item? 
Which submenu? 

The information is divided in three bit groups. The division is as follows: 



Bits 


0- 4 


Bits 


5-10 


Bits 


11- 15 



Menu title number 
Menu item number 
Submenu item number 



The numbering begins with zero — ie the first menu point of the first 
menu has the numbers and 0. 

To try this out insert the following lines: 



move 


d7,d6 


lsr 


#8,d7 


lsr 


#3,d7 


clr.l 


d5 


roxr 


#l,d6 


roxl 


#l,d5 


and.l 


#$7f,d6 


cmp 


#$7f,d6 


beq 


loop 


lsr 


#4,d6 



;Move code into D6 
jShift right 11 times 
;Submenu item now in D7 

;Bit in X-f lag 

jMenu number now in D5 

Jlssolate lower bits 

;No menu item? 

;No: continue 

JElse menu item in D6 
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ende: 

By making a test run with AssemPro, you can easily see if this works 
right— just look at the registers after the program is over. 

If you, for example, want to write a program with four menus with 10 
menu items each, this sort of method is to much work — there are 44 
tables. For this reason, let's look at a short program that takes care of the 
necessary structure table itself. 

The menu structure is built very simply — it doesn't offer submenus or 
the option of choosing items via the keyboard. If you want these extras, 
you can still use this program, but you'll have to use MOVE commands 
to insert the desired flags and pointers. 

The input that this program needs is a list of the menu names and the 
items in each menu. The addresses of the menu texts go in a table with 
the following simple form: 

del Menu title 1 

del Pointl, Point2, Point3, ...,0 

del Menu title 2 

del Pointl, Point2, Point3, ...,0 

del Menu title 3 oder 

This program is set up in such a way that up to four menus can lie next 
to each other (in normal screen resolution), which is often plenty. The 
table above ends by putting a zero instead of a pointer to the next menu 
title. As you can see, it's pretty simple. 

This program is inserted into your big program right behind the 
"setmenu" label. After the "bsr setmenu" command is executed, the menu 
structure is built and initialized at the same time. You don't need to 
change the rest of the program, it'll be shorter that way. 

Here's the program fragment for the complete "setmenu" routine: 



setmenu: 




lea 


mentab,a0 


lea 


menu,al 


move 


#10,dl 


menuloop: 




clr.l 


d2 


move.l 


al,a2 


tst.l 


(a0) 


beq 


setmenul 


clr.l 


(al) + 


move 


dl,(al) + 


add.l 


#70,dl 


move.l 


#50,(al) + 



;* Initialize menu structure 
jPointer to text pointer in A0 
jPointer to menu field in Al 
jHorizontal menu position = 10 

jVertical menu position = 

;Save address for pointer 

JAnother menu there? 

;No: quit 

; M No more menus" preparations 

;Set X-position 

;And increment 

;Y-position and width 
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move.l 

move.l 

lea 

move.l 

clr.l 

clr.l 

itemloop: 

tst.l 

beq 

lea 

move.l 

move.l 

add 

move.l 

move 

clr.l 

lea 

move.l 

clr.l 

clr.l 

clr.l 

move 

clr 

move.l 

clr.l 

move.l 

clr.l 

bra 

menuend: 

clr.l 

tst.l 

tst.l 

beq 

move.l 

bra 

setmenul: 

move.l 

move.l 

lea 

jsr 

rts 



#$a0001,(al) + jHeight and flag 



<aO)+,(al) + 
12(al),a3 
a3,(al) + 
(al) + 
(al) + 

(aO) 

menuend 
54 (al),a3 
a3,(al) + 
d2,(al) + 
#10,d2 



JMenu title 

JPointer to menu item 
jReserved words 



jLast entry? 
;Yes: menu done 

JPointer to next item 
;X- and Y-position 
;Y-position +10 



#$5a000a, (al)+ jWidth/Height 



#$52,(al) + 
(al) + 
16(al),a3 
a3,(al) + 
(al) + 
(al) + 
(al) + 
#$l,(al) + 
(al) + 

#$50003,(al) + 
(al) + 

(a0)+,(al) + 
(al) + 
itemloop 

-54(al) 
<a0) + 
(aO) 

setmenul 

al,(a2) 

menuloop 

intbase,a6 
windowhd,aO 
menu,al 
SetMenuStrip (a6) 



jFlag: normal 
;No connection 

jText structure pointer 

;No fill structure 

;No command, no submenu 

jAnd no continuation 

;Set text structure: color 

jMode 

;X- and Y-positon 

jStandard character set 

JText pointer 

;No continuation 

jNext item... 

jEventual transfer to next menu 

jErase pointer to next item 

JIncrement table pointer 

jAnother menu there? 

;No: done 

JPointer to next menu 

jAnd continue 

J* Initialize menu (like before) 

Jlntuition base address in A6 

jWindow structure in AO 

JPointer to menu structure 



You need three things yet for this program: the memory to be used for the 
structure, the table of text pointers and the text Here's an example: 



mentab: 

del menul 

del mpll,mpl2,mpl3 

del 

del menu2 

del mp21,mp22,mp2 3 

del 

del 
J** Menu Text ** 
menul: deb "Menu 1",0 



jFirst menu title 

jMenu items 

jEnd of menu 1 

jSecond menu title 

JMenu items 

JEnd of menu 2 

JYou ' re out of menus ! 
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mpll: dc.b "Pointll ,, ,0 
mpl2: dc.b "Pointl2",0 
mpl3: dc.b "Pointl3",0 
menu2: dc.b "Menu 2",0 
mp2l: dc.b "Point 21", 
mp22: dc.b "Point 22", 
mp23: dc.b "Point 23", 

align 
;** Storage space for menu structure ** 
menu: blk.w 500 

Make sure that the memory area reserved for the menu structure is big 
enough and change the entry "blk.w 500" to the calculated value. 

If you use this program, and want to build some special features into the 
menu (for instance key commands), you can make entries in the menu 
structure table while the program is running. You can find the word (or 
byte or long word) that interests you in the table as follows: 

For example, to find the keyboard command byte of the second entry in 
the first menu, calculate as follows: 

Address = Start_address + Menu*30 + (Entry-1) *54 +26 

which in the example comes to: 

Address = menu + 30 + 54+26 
= menu + i 10 

The 26 is the distance from the beginning of the Menultem structure to 
the desired byte, the command byte. In this way, you can calculate the 
addresses and use MOVE commands to modify the menu to fit your 
wishes. By the way, in the example above, the corresponding flag bit 
must be set as well, so that the keyboard command is recognized! 

Now let's get back to the window. It's nice to have a window that you 
can change and close, but you really want to be able to output text in a 
window! 
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It's very easy to use Intuition's text output function. Use the PrintTText 
function (offset -216). It needs four parameters. 

In AO A pointer to the RastPort of the window. You can find this in 

the window structure. 
In Al A pointer to the text structure of the text that should be output 
In DO The X-position 
In Dl The Y-position of the text in the window 

It's very easy to enter the X- and Y-positions. You've already used the 
text structure twice (for requesters and menus). 

What's new is accessing the windows's RastPort. The RastPort is a struc- 
ture that describes the window. The address is needed by several Intuition 
functions. 

The pointer to the RastPort starts at the 50th byte in the window struc- 
ture. You can access it as follows: 

move.l windowhd,aO jAddress of window structure 

move.l 50(a0),a0 ;RastPort address in AO 

Now you've got the address of the RastPort. Let's write a routine that 
prints a text. The X- and Y-positions are in DO and Dl respectively and 
the address of the text structure in Al before the routine is called: 

PrintlText = -216 

print : 

move.l intbase,a6 JIntuition base address in A6 

move.l windowhd.aO JAddress of window structure 

move.l 50(a0),a0 jRastPort address in AO 

jsr PrintlText (a6) ;Call function 
rts 

You can try out this routine by using the requester's text that is still in a 
structure of the program. Write the following lines before the "loop" 
label: 
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lea btext,al 

move.l #10, dO 

move.l #30,dl 

bsr print 



Pointer to text structure in Al 
;X-position 
;Y-position of text 
;Output text 



Start the program and the text appears in the middle of the window. If this 
doesn't happen, check the color of the text in the text structure. It's prob- 
ably zero. Just change it to three, and the text appears in red the next time 
you start the program. 
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7.7 Images 



An Image is a drawing that goes in a rectangular field and is defined 
bitwise. The disk symbol of the Intuition screen and the system gadgets 
in the screen and window borders are examples of such Images. 

The rectangle that the drawing goes in can be arbitrarily large, but each 
pixel in the rectangle needs its own bit, so programming screen-sized 
Images isn't advisable. You'll stick to an Image that requires about 32x16 
bits — an Image that's about 3x1 cm. 

You can make all sorts of images as you've seen looking at window 
gadgets. There is an Intuition function that draws an Image: It is the 
Drawlmage function (offset -1 14) and it needs 4 parameters: 

In AO The address of the RastPort image is drawn in. You've already 
learned how to access this address in the section on the text func- 
tion. 

In Al The structure address of the Image to be drawn 

In DO The relative X-position 

In Dl The relative Y-position of the drawing 

Let's draw this picture in your window. It just takes a simple routine. 
You just need to put the address of the Image structure in Al and the 
position of the image in E>0 and Dl before you call it. 



Drawlmage = -1 


14 




draw: 




;* Draw Image 


move.l 


intbase,a6 


;intuition base address in A6 


move.l 


windowhd, aO 


jPointer to window structure 


move.l 


50(a0),a0 


;Now, RastPort address in AO 


jsr 


Drawlmage (a6) 


;Draw image 


rts 







Now you need the structure of Image. The structure contains nine entries 
which have the following meanings: 

The first two entries are words which specify the distance in the X- and Y- 
direction from the coordinates that were given to tell where the Image 
should be drawn. You'll just put two zeros here: 
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image: 

dew 0,0 ;X- and Y-position 

Next come two words which specify the width and height of the Image in 
pixels. Let's draw a 32x13 point Image. Enter: 

dew 32,13 ;Width and height of the Image 

The next word in the list specifies the number of planes in the drawing. If 
it's a simple Image that only uses two colors, just enter a one. For more 
colors, you'll need a correspondingly bigger number. When more colors 
are worked with, the bit pattern of the Image must have more data. Let's 
just have one bit plane: 

dew 1 ;0ne bit plane: 2 A 1=2 colors 

Next comes a long word that points to the data for the Image: 

del imgdata JPointer to image data 

The next two bytes are very interesting. The first byte, the PlanePick 
byte, tells which plane of the window or screen the Image data should be 
written in. Since you only have one plane, you need to enter the bit plane 
of the window. This information is found in the bits of this byte — bit 
stands for plane 0, bit 1 for plane 1, etc... You also define the color of the 
Image with this input. If you enter a two, every set bit of your Image rep- 
resents a red point 

deb 2 jDrawing red: plane 1 

The second byte, the PlaneOnOff byte, is an interesting enhancement. 
Each bit of the window bit plane corresponds to a whole number here. 
The only bytes that are interesting though are the ones that are cleared in 
the PlanePick byte. If the bit is set in PlaneOnOff, every bit of the Image 
in the corresponding plane is set. Otherwise they are cleared. To make 
sure that each bit of the Image that isn't set appears white, enter a one. 
All the bits of the Image that aren't set, are set in Plane 1 and appear 
white. 

deb 1 jBackground: white 

The last entry of the structure is a long word that points to another 
Image. You don't need this, so set the long word to zero: 

del ;No more Images 

Here's a quick overview of the Image structure: 
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dew 


0,0 


dew 


32,13 


dew 


1 


del 


imgdata 


deb 


2 


deb 


1 


del 
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image: 

;X- and Y-position 

jWidth and height of the Image 

;0ne bit plane: 2^1=2 colors 

jPointer to image data 

JDrawing red: plane 1 

jBackground: white 

;No more'llmages 

Now let's produce the Image data. Each Image row uses a word, long 
word, or several of these to represent the pattern. The set points of the 
Image correspond to the set bits. This is repeated as often as the height of 
the Image requires. The data on each line must begin on a word border, on 
an even address. 

For the example, it's easy to decide on the data, since you're going 32 
points across — that corresponds to exactly one long word. It's easiest to 
program the Image using the binary representation of the data. 

Let's use, as an example, an image that repressents a switch in "OFF" 
mode. This form is chosen for a good reason, so you should type it in. In 
the chapter on gadgets that's coming up, we'll show you how to turn the 
switch on. Here is the example data for the switch Image: 

imgdata: JData for switch in "OFF" mode 

del %0000 000000000000000 0000000000000 

del %0000 000000000000000 01 11 000000000 

del %0001 11011101 1100000 11 11 100000000 

del %0001 010100010000000 11 11 100000000 

del %0001 01011 001 1000000 11 11 000000000 

del %0001 110100010000001 1100000000000 

del %00000000000000000 11 1000000000000 

del %0000 0000000000001 11 00 00000000000 

del %00000000000111111 11 1100000000000 

del %000000000011 1111 11 111 10000000000 

del %0000 000000 11 111 11 1111 10000000000 

del %000000000001 100000011 0000000000 

del %00000000000000000000000 000000 000 

Once you've typed this data, you can experiment with displaying it on the 
screen. Enter the following lines before the "loop" label: 

move.l image, al JPointer to Image structure 

move #30, dO ;X-position in window 

move #50, dl ;Y-position 

bsr draw ;Draw image 

How do you like the Image on the screen? You'll run into this switch 
again when we talk about putting the switch in the "ON" state when dis- 
cussing gadgets. You need to look at other methods of drawing in the 
window first, though. 
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7.8 Borders 



A border is a collection of lines that are connected. They can be of any 
length or at any angle. Intuition lets you draw borders to do things like 
put frames around windows and screens. They are used to put borders 
around pictures or text, especially for use with string gadgets. We'll talk 
about that later, though. 

It's easy to draw borders. Just use the Intuition function DrawBorder (off- 
set -108) which needs four parameters: 

In A0 The RastPort address of the output medium the lines should be 

drawn in. Use your window. 
In Al The address of the border structure. We'll look at the form of this 

structure shordy. 
In DO The relative X-coordinate which is used with the X- and Y- 

coordinate list to calculate the actual line coordinates. 
In Dl The relative Y-coordinates. Relative, here too, means that this is 

relative to the upper left corner of the screen. 

Let's write a short routine that is called with three parameters. The struc- 
ture address is in A 1 and the X- and Y-coordinates are in DO and Dl 
respectively when the routine is called. The border is drawn in the window 
whose structure address is in "windowhd". 



* Draw several lines 
Intuition base adcdress in A6 
Pointer to window structure 
Now RastPort address is in A0 



Now let's look at the border structure. The list needs the eight following 
parameters: 

First, you need two words for the vertical and horizontal distance from the 
coordinates given in the function call. To avoid losing sight of some of 
the many distance entries, put zeros here: 



DrawBorder = - 


108 


borderdraw: 




move.l 


intbase, a6 


move.l 


windowhd, aO 


move.l 


50(a0) ,a0 


jsr 


DrawBorder ( 


rts 
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border: 

dew jHorizontal distance 
dew jVertical distance 

Next come two bytes that determine the color. Use a red frame: 

dc.b 3 JRed frame 

dc.b JBackground (unused) 

As you can see, the background color isn't used. You have two modes to 
choose between for drawing the lines. The following mode determines the 
mode that is used. If it is zero, each line is drawn in the color chosen, no 
matter what was before. This is the J AMI mode. The other mode is the 
XOR mode which ignores both color entries. In this mode, all the points 
that lie under the line have their color value inverted. As a result, a white 
point becomes black, and a blue one becomes red. That is mode two. 
Let's use the JAM1 mode for the example: 

dc.b ;Mode: JAM1 (2=X0R) 

The next entry specifies how many coordinate pairs there are in the list. 
Since this word must be on an even address, you need to use the "align" 
pseud-op first. Then enter the number of pairs. Remember that you need 
three points to draw two lines: beginning, corner and end point. To draw a 
rectangular frame, you need five pairs: 

dc.b 5 ;5 X,Y pairs used together 

The next item is a pointer to the coordinate table that contains a list of 
points to be connected: 

del coord jPointer to coordinates table 

The border structure's final entry is a long word that can point to another 
border structure. If you don't have any more structures to be pointed to, 
just enter a zero here. The pointer is useful for connecting two indepen- 
dent border structures — for example, to produce a two colored frame that 
really stands out You don't need this pointer in the example, though: 

del ;No more structures 

That's the border structure. Now let's look at the coordinate list. For the 
example, it consists of five pairs of numbers which represent a rectangle. 
I recommend entering these values, because you'll use them in example 
programs further down the line. 
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coord: jCoordinates for rectangular frame 



dew 


-2,-2 


dew 


80,-2 


dew 


80, 9 


dew 


-2,9 


dew 


-2,-2 



Here's a quick overview of the border structure: 



border: 








dew 







dew 







deb 


3 




deb 







deb 







deb 


5 




del 


coord 




del 





coord: 








dew 


-2,-2 




dew 


80,-2 




dew 


80, 9 




dew 


-2, 9 




dew 


-2,-2 



jHorizontal distance 

jVertical distance 

;Red frame 

;Background (unused) 

jMode: JAM1 (2=XOR) 

;5 X,Y pairs used together 

jPointer to coordinates table 

;No more structures 

;Coordinates for rectangular frame 



Once you've typed this in, you can try the whole thing out Type the fol- 
lowing lines before the "loop" label in the program: 

lea border, al ;Address of the border structure 

move #20, dO ;X base position 

move #80, dl ;Y base position 

bsr borderdraw ;Draw frame 

As you can see, using enough X- and Y -coordinates, you can draw the 
Eiffel tower. That's enough about simple drawings. You want to put 
some life into your drawings and text. Let's manipulate them with the 
mouse! 
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7.9 Gadgets 



We already talked a bit about gadgets when you looked at screen construc- 
tion. Looking at system gadgets like the window close symbol, you can 
activate by clicking and causes a program function to be executed. 

You can make your own gadgets as well. Intuition allows you a lot of 
interesting possiblities. 

There are four types of gadgets: 

Boolean gadgets are used in Yes/No situations. You can click 
and activate it (Yes) or deactivate it (No). 

• String gadgets are used to accept input of text of a specified 
length. 

Integer gadgets are a special sort of string gadgets which accept 
the input of a decimal number. Intuition converts the value into 
a long word and sends it to the program. 

• Proportional gadgets let you choose an analog value with the 
mouse. You can move these around with the mouse. 



7.9.1 Boolean gadgets 



Let's start with the simplest type, the boolean gadget An example of this 
sort of gadget is the close symbol of the window. The only status it 
differentiates between are clicked and not clicked Let's develop a gadget of 
this type step by step. The flags and other parameters are similar for the 
other gadgets. 

Each gadget needs a structure containing fifteen entries. There is a pointer 
to this structure in window, screen or requester that the gadget is to appear 
in. There's always a long word available for this purpose. Up to this 
point, you've just put a zero there. If there is an address of a gadget struc- 
ture there, the gadget or gadgets are displayed when the window is opened. 

A gadget structure has the following entries: 

The first long word is a pointer to the next gadget to be installed. The 
gadgets are displayed in a row, like pearls on a string. This pointer is the 
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first gadget in this linked list of gadgets. If you just want one gadget in 
your window, put a zero here: 

gadgetl: 

del ;No more gadgets 

The next two words determine the position of the gadget in the window. 
There are several ways to determine the position. Use flags to access the 
various possibilities. Let's start with a gadget that stays in one spot: 

dew 40 ;X- and 

dew 50 ;Y-position of the gadget 

The next two words determine the size of the gadget's Hit box. This box 
isn't the visible size of the gadget (that depends on the Image data). It is 
the size of the rectangle that Intuition should watch. If the mouse pointer 
is moved into this box and the left button is pressed, the gadget is acti- 
vated. Clicking on parts of the gadget that are outside this box have no 
effect! 

dew 32 ;Width and 

dew 13 ;Height of the Hit box 

Next, comes the word whose bits determines the properties of the gadget. 
Bits and 1 determine what should happen when this object's hit box is 
clicked on. The meanings of the various values of these bits go as 
follows: 

BitO 1 Value Name Meaning 

The gadget inverted 
The gadget framed 
Another Image appears 
No reaction 

Bit 2 determines whether the gadget should consist of a drawing or a bor- 
der. If it is set (Value +4), it is treated as an image; otherwise it's treated 
like a border. 

The next bit determines if the gadget should appear in the upper or lower 
border of the frame. If it is set (Value +8), the position is relative to the 
lower border; otherwise it is relative to the upper border. The next bit has 
the same meaning for the horizontal position. If set (Value +$10), it is a 
relative positioning. Otherwise, it is an absolute positioning. 

Notice that when you define a gadget to be relative, you must have a neg- 
ative value in the position input in the first word of the structure. Since 
the desired positon isn't under, but is over this position! 
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GADGHCOMP 





1 


1 


GADGHBOX 


1 





2 


GADGH IMAGE 


1 


1 


3 


GADGHNONE 
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In this way, you can choose either absolute or relative positioning of the 
gadget. An example of a gadget that is positioned absolutely is the sys- 
tem gadget, close window. An example of a relative gadget is the symbol 
for changing the size. 

The width and height of the gadget's hit box can also be relative to the 
window size. Specify this by using bit 5 for width (Value +$20) and bit 6 
for the height (Value +$40). A set bit means a relative size. 

Bit 7 (Value +$80) makes the object active as soon as the window is 
opened. 

Bit 8 (Value +$100) determines whether the gadget can be used or not. If 
this bit is set, the gadget can't be activated. 

For the example, you'll use absolute positioning and size, the inverted 
appearance for the activated gadget, and the representation of the object as 
an image. That means you must use the value four: 



dew 



;Flags: Image, invert 



Next comes a word whose bits are used as flags. This flag is called the 
Activation Flag. It determines the functions of the gadget. The bits, their 
values and meanings follow: 



Bit Value Name 



Meaning 



1 RELVERIFY 

1 2 GADGIMMEDIATE 

2 4 ENDGADGET 

3 8 FOLLOWMOUSE 



5 
6 

7 



$10 RIGHTBORDER 



$20 LEFTBORDER 
$40 TOPBORDER 
$80 BOTTOMBORDER 



Causes the gadget to be activated only 
when the left mouse key is let loose 
over the gadget 

Let's the gadget be active as soon as 
there is a click. 

Let's you choose to end this choice and 
have it disappear if this is a Requester 
gadget 

Let's the gadget know the mouse posi- 
tion at regular intervals from the time it 
is selected until the time it is deselected. 
You can use this to move the gadget 
with the mouse when you want to 
change the gadget position. 
This makes sure that when borders are 
used that the page is adjusted to the size 
of the gadget so that it fits in the 
border. 
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8 $100 TOGGLESELECT 



$200 STRINGCENTER 



10 $400 STRINGRIGHT 

11 $800LONGINT 

12 $1000ALTKEYMAP 



Allows the object's state to change 
every time it is clicked. If activated, it 
becomes deactivated and vice versa. 
For a string gadget, these two bits deter- 
mine whether the string should appear 
centered or right justified. If neither is 
set, the string is output left justified. 

Turns a string gadget into an Integer 
gadget (explanation later). 
Causes another key board placement to 
be in effect for string gadget input 



That's it for the activation flags. Let's choose the TOGGLESELECT and 
GADGETIMMEDIATE flags for the example: 



dew 



$102 jActivation 



The next word of the gadget structure determines the gadget type. Here is 
the meaning of the individual bits: 



Bit 


Value 


Name 


Meaning (report what circumstances) 





1 


BOOLGADGET 


This is a boolean gadget. 


1 


2 


GADGET002 




2 


4 


STRGADGET 


String order Integer gadget 


0+1 


3 


PROPGADGET 


Proportional gadget 


System 


gadgets: 






4 


$10 


SIZING 


Size changing gadget 


5 


$20 


WD RAGGING 


Moving gadget for window 


4+5 


$30 


SDRAGGING 


Same for screen 


6 


$40 


WUPFRONT 


Gadget to move window forward 


6+4 


$50 


SUP FRONT 


Gadget to move screen forward 


6+5 


$60 


WDOWNBACK 


Move window back 


6+5+4 


$70 


SDOWNBACK 


Move screen back 


7 


$80 


CLOSE 


Window close gadget 



Type definitions: 

12 $1000 REQGADGET 

13 $2000 GZZGADGET 

14 $4000 SCRGADGET 

15 $8000 SYSGADGET 



Requester gadget 

Border gadget in GIMMEZERO- 

ZERO window 

Screen gadget when set 

System gadget when set 



You want to use a simple boolean gadget for your example, so enter: 



dew 



jGadget type: boolean 



Next comes a pointer to the gadget structure. The first pointer contains 
the address of the Image or border structure which should be used to repre- 
sent the gadget. If no representation is needed, put a zero here. You want 
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to represent the gadget as an Image, so put a pointer to the Image struc- 
ture that you produced in the chapter about Images: 

del image ;Gadget Image 

The next pointer is only used if the G ADGHIMAGE flag in the flag word 
of the structure is set. This is a pointer to another structure that should be 
put on the screen when the object is activated. If a border structure is used 
for the gadget representation, this must be a border structure as well. You 
won't use a second Image, so put a zero here: 

del ;No new gadget displayed 

The next pointer is to the text structure that should be output by the gad- 
get. If no text is needed, just put a zero here. You want to use some text, 
however: 

del ggtext ;Gadget text 

Next comes a long word that determines which gadgets are deactivated 
when this is activated. This function still doesn't work right so put a zero 
here: 

del ;No exclude 

You'll set the next pointer to zero as well, because it is only used for 
String and Proportional gadgets. For these gadgets, this is a special struc- 
ture to describe the characteristics of the gadget. It's called Speciallnfo. 

del ;No Speciallnfo 

The next word contains the Gadget Identification (ID) number: 

dew 1 jGadget ID 

Finally there is a long word that doesn't have any function, so put a zero 
here: 

del ;Userdata (ignored) 

That's it. Here's a quick overview of the gadget structure: 

gadgetl: 

del ;No more gadget s 

dew 40 ;X- and 

dew 50 ;Y-position of the gadget 

dew 32 ;Width and 

dew 13 ;Height of the Hit box 

dew 4 ;Flags: Image, invert 

dew $102 ;Activation flags 
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dew 


1 


jGadget type: boolean 


del 


image 


jGadget Image 


del 





;No new gadget displayed 


del 


ggtext 


jGadget text 


del 





;No exclude 


del 





;No Speciallnf o 


dew 


1 


jGadget ID 


del 





;User data (ignored) 



You've already prepared a structure that you can use for the Image. Now 
you need the text that appears under the gadget. 

Since this gadget looks like a switch, label it "Switch". The text structure 
looks like this: 



ggtext: 




deb 1,0 


JColors 


deb 1 


;Mode 


align 




dew -8,14 


;X- and Y-position 


del 


jStandard font 


del swtext 


jPointer to text 


del 


;No more text 


swtext: 




deb "Switch", 




align 





Once you've typed this in, save it, assemble it and start it You can click 
the switch and cause it to be inverted. Click it again, and it appears 
normal. 

Now you can experiment with the structure. If you change the flag from 
four to five, you can cause the gadget to be framed when it is activated. 
Set the REL VERIFY bit (Bit 0: +1) in the Activation Flag word. Then 
you can move the mouse pointer onto the object and press the button. It 
is activated. Keep the mouse button pressed down and move the mouse. 
Once you leave the Hit box, the activation disappears. This way, you can 
avoid accidently activating a gadget. 

Now you want to display the switch in an on state. This is easy. All you 
need to do is produce another Image structure, one for the on state. You 
put this pointer in the long word right after the pointer to the normal 
Image structure. You change the flag word to six which causes a second 
Image to be displayed when the gadget is activated. 

Here is the Image structure for the switch in the on state. 
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image2 : 

dew 0,0 ;No offset 

dew 32,13 ;32xl3 pixels 

dew 1 ;Mode 1 

del imgdata2 jPointer to the data 

deb 2,1 ;Same colors as before 

del jNothingelse 

imgdata2: ;Data for switch in the ON state 

del %00000000000000000000000000000000 

del %00000000011 100000000000000000000 

del %0000000011111000001 1101001000000 

del %000000001 11110000010101 101000000 

del %00000000011110000010101011000000 

del %00000000000111 00001 1101001000000 

del %00000000000011100000000000000000 

del %00000000000001 11 0000000000000000 

del %00000000000111111111100000000000 

del %00000000001 11111 11 11 110000000000 

del %00000000001111 111 111 110000000000 

del %00000000000110000001 100000000000 

del %00000000000000000000000000000000 

Now the state of the object can be determined by looking at the picture. If 
the gadget is activated, the switch is on. If not, the switch is off. 

That's it for Boolean gadgets. You can learn about the things you didn't 
touch with some experimentation. You want to get to the string gadgets 
that also do some interesting things. 



7.9.2 String gadgets 



Let's pretend you want a program to load data from the disk. To get the 
user to enter the filename, you need to output text telling the user to enter 
the name. Then you need to call an input routine to evaluate the keyboard 
input. 

It's easier and more elegant to use a String gadget. This function allows 
for easy input and/or editing of short text You have the option of having 
the text framed. The Undo function can be used by pressing the right 
<Amiga> key and a "Q", and the old contents of the gadget, the old text 
are restored. 

You can also vary the size of the text and the input field. If the text is 
longer than the input field is wide, the text is moved back and forth 
through the visible area when you move the cursor keys or the normal 
input to the border. 
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You can also restrict input to just digits. This makes it possible to accept 
numeric input. Intuition even converts the digit string into a binary 
number. This saves the machine language programmer some work. A 
specialized String gadget of this sort is called an Integer gadget 

The structure is similar to the Boolean gadget's structure. There are only 
two major differences: 

The type word of the structure must be a four to declare that this is a 
String gadget (STRGADGET). 

The pointer to the Speciallnfo structure is needed. Put a pointer to the 
Stringlnfo structure that you are going to design later here. 

The width and height entries in the gadget structure have a different mean- 
ing than they had previously. They do declare the area in which you can 
bring the mouse pointer to activate the String gadget However, it is also 
used for the representation of text. These values determine the size of the 
box in which the text is output. You should surround the box with a 
border using the Border function, so that the user can see where it is. 

If the text is longer than the box, only a portion of it is seen on the 
screen. You can move through the area by entering text or using the 
left/right cursor keys to move through the box. The characters that are 
entered are inserted at the cursor position, so the rest of the text is shifted 
by one character when you are on the right edge of the input area. The 
following functions can be used for editing this text: 

Cursor key left/right 

Moves the cursor over the text that's already on hand. Moves the 
text through the Container. 

Cursor keys with <Shift> 

Puts the cursor on the beginning or the end of the text 

<Del> Deletes the character under the cursor. 

<Backspace> 

Deletes the character to the left of the cursor. 

<Retum> 

Ends text input 

<Amiga> right + "Q" 

This is the Undo function. It replaces the text with the original 
contents. 
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The Stringlnfo structure only has a few entries: 

First there's a pointer to the memory area that is used to store the text 
that is input. The memory buffer must be big enough to handle all the 
text entered. 

strinf o: 

del strpuffer ;Pointer to text buffer 



Next comes a pointer to the Undo buffer. This pointer and this buffer are 
only needed if you want the Undo function. If you do, you must have a 
buffer that is at least as big as the text buffer. Every time the string 
gadget function is called, the text buffer's contents are copied into this 
buffer. To get the old contents back, just press the right <Amiga> key 
and the "Q" key. The contents of the Undo buffer are copied back to the 
text buffer. If you use several String gadgets in a program, you can use 
the same Undo buffer for all of them, since only one String gadget is used 
at a time. 

del undo JPointer to Undo buff er 

The following word contains the cursor position in the text. You should 
set this word to zero, so that the user can see the beginning of the text 
when the String gadget appears. 

dew jCursor position 

The next word contains the maximum number of characters that can be 
input. If you type one more than this number of characters, the screen 
blinks, to show that you can't enter a longer input string. The number of 
characters and the reserved space for the input field don't have to agree, 
since text can be scrolled by typing. 

dew 10 jMaximum # of characters 

The following word tells at which character of the text in the buffer, the 
output to the box should begin. You should put a zero here, so that the 
user can see the beginning of the text. 

dew ;Output text from this character 

The next five words are used by Intuition, so you don't have to initialize 
them. Just put zeros here. The words contain the following information: 

;Character position in Undo buffer 
JNumber of charsin text buffer 
JNumber of chars visible in box 
jHorizontal box offset 
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dew ;Vertical box of f set 

The next two long words are initialized by Intuition as well: 

del jPointer to RastPort 

del ;Long word with value of the input 

; ;(f or Integer gadgets) 

The final entry is a pointer to the keyboard table that is used if the 
ALTKE YMAP flag of the gadget is set 

del JStandard keyboard table 

Here's a quick overview of the Stringlnfo structure: 



JPointer to text buffer 
JPointer to Undo buffer 
jCursor position 
jMaximum # of characters 
jOutput text from this character 
JCharacter position in Undo buffer 
jNumber of chars in text buffer 
JNumber of chars visible in box 
jHorizontal box offset 
jVertical box offset 
JPointer to RastPort 
;Long word with value of the input 
; ;( for Integer gadgets) 

del ;Standard keyboard table 

Here are the text and Undo buffers: 

strpuf fer: 

deb "Hello ! ",0,0,0 
undo: 

del 0,0,0,0 
align 

Once you've entered these lines, you can either alter the old gadget 
structure or build a new one. We'd recommend building another gadget 
structure so that you can have the switch and use it later. Change the first 
pointer in the old structure from zero to "gadget 1" and insert this new 
structure. Here is an example structure for the String gadget. It has the 
following entries: 



strinf o: 




del 


strpuf fer 


del 


undo 


dew 





dew 


10 


dew 





dew 





dew 





dew 





dew 





dew 





del 





del 






gadgetl: 




;* Structure for String gadget 


del 





;No more gadgets 


dew 


20,80 


JPosition 


dew 


80,10 


jWidth and height of box 


dew 





jFlags: normal 


dew 


2 


jActivation ($802 for long int) 


dew 


4 


;Type: String gadget 
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del 


border 




del 







del 







del 







del 


strinfo 




dew 


2 




del 





border: 








dew 


0,0 




deb 


3,3 




deb 







deb 


5 




del 


coord 




del 





coord: 








dew 


-2,-2 




dew 


80,-2 




dew 


80,9 




dew 


-2,9 




dew 


-2,-2 



jPointer to border 

;No drawing selected 

;No text 

;No exclude 

;Pointer to Stringlnf o structure 

;Gadget ID 

;No user data 

;* Border for box frame 

;No offset 

;Red color 

jMode: JAM1 

;5 X,Y pairs 

jPointer to coordinates table 

;No more structures 

;* Coordinates for frame 

;Start in upper left corner 

jUpper right 

;Lower right 

;Lower left 

jBack to beginning 



This data causes a red rectangle, the Border, to appear around the "Hello !" 
text. You can change the text by clicking in the field and editing once the 
cursor appears. If you type something wrong, you can use the Undo 
function (The right <Amiga> key and the Q key), to get "Hello !" back. 

Once you've done some typing and deactivated the gadget by pressing 
<Return> or by clicking outside the field (Cursor disappears), you can 
terminate the program. 

Change the Activation flag to $802 and the "strbuffer" to "dc.l 0,0,0,0", 
assemble, and then start the program. You can type in the string gadget 
once it has been activated, but you can only enter digits. The screen 
blinks if you enter letters. 

Enter a number, and then end the program after deactivating the gadget. If 
you look at the Stringlnfo structure you can look at the value of the 
number you input (in hex) in the eighth long word. 

After looking at boolean, text and numeric input to gadgets, let's look at 
Proportional gadgets which allow the user to enter analog values by mov- 
ing a symbol. 
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7.9.3 Proportional gadgets 

You've seen the advantages of slider devices over knobs that you turn, 
maybe on a Hi Fi, maybe on a toaster, but certainly someplace. It's easier 
to tell the state the item is in with a slider, especially if several such 
devices are next to each other (for example graphic equalizers). You can 
represent sliders on the Amiga's screen and work with them with the 
mouse. This offers a nice way to represent information graphically in 
your programs. 

You can do this with gadgets. Using Proportional gadgets, you can put a 
symbol in a frame and move it horizontally and/or vertically. The size of 
the frame and the slider can be of variable size, so that the frame size is 
relative to the screen size so when the window changes size, it will also. 
The slider can be set up so that its size in the frame grows or shrinks. 

These options are best seen via example and experimentation. (The 
possibilities mentioned do not form a complete list by any stretch of the 
imagination.) You want to set up a simple Proportional gadget that can 
be moved horizontally. 

You need a gadget structure that has the same form as the others. To 
show the differences, here's a complete example structure for your gadget. 
You can connect this gadget to the other one, by changing the first long 
word in the last structure to "del gadget2". 



gadget2: 




;* Structure for Proportional 
gadget 


del 





;No more gadgets 


dew 


150,30 


;Position 


dew 


100,10 


;Width and height of frame 


dew 


4 


jFlags: GADGIMAGE 


dew 


2 


jActivation: GADGIMMEDIATE 


dew 


3 


;Type: Proportional gadget 


del 


mover 


jPointer to slider data 


del 





;No select structure 


del 





;No text 


del 





;No exclude 


del 


propinf o 


jPointer to Proplnfo structure 


dew 


3 


jGadget ID 


del 





;No user data 



You see two special features. Use an Image structure for the mover and 
put a pointer to another structure in the spot for the Speciallnfo pointer. 

First, let's look at the "mover" structure, the slider's Image structure. 
Here's an example of this structure: 
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mover: 

dew 0,0 

dew 16,7 

dew 1 

del moverdata 

deb 1,0 

del 

moverdata: 

dew%0111111111111110 
dew %01011111 11111010 
dew%0101011111101010 
dew %01 01 01 01 10 10 10 10 
dew %01 010111 11101010 
dew%0101111111111010 
dew%0111111111111110 



;* Structure for slider image 

JNo offset 

;16x7 pixels big 

;0ne bit plane 

;Pointer to image data 

jColor: white 

;Don ' t continue 

;* Image data for mover 



Up till now, there wasn't anything new. Now let's look at the Proplnfo 
structure that describes the properties of the Proportional gadget. 



The structure starts with a flag word that contains the following flag bits: 



Bit Value 



Name 



Meaning 






1 


AUTOKNOB 


1 


2 


FREEHORIZ 


2 


4 


FREEVERT 


3 


8 


PROPBORDERLESS 


8 


$100 


KNOBHIT 



Mover is set up automatically 
Allows horizontal movement 
Allows vertical movement 
Turns off automatic framing 
Set when the mover is touched 



You can set the first four bits to get the representation that you want. Bit 
8 is set by Intuition when the mover is clicked with the mouse pointer. 

Bit 0, AUTOKNOB, allows for the simplest sort of Proportional gadget. 
If this bit is set, no move data are used for the mover Image. Instead, a 
white mover is generated that is adjusted to the size of the box and the 
value to be represented. When you use this slider to represent the 
displayed lines in a long text of a text program, the displayed lines are a 
percentage of the total text. The relationship between the total number of 
lines and the lines shown is represented by an AUTOKNOB as the 
relationship between the frame and the slider. The bigger the percentage, 
the bigger the slider is. You don't want to work with this though, even 
though it is simple and interesting, because a simple white button isn't 
particularly attractive. If you experiment with it, make sure that the 
pointer to the Image data points to a four word long buffer that Intuition 
can use to store values. The buffer is of the following form: 



buffer : 



dew ;X-position of the slider in the box 

dew ;Y-position in the box 

dew ;Width of slider 

dew jHeight of slider 
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Let's look at the Proplnfo structure. Since you're not using AUTOKNOB 
and wish to allow horizontal movement only, put two in as a flag: 

propinf o: 

dew 2 jFlags: FREEHORIZ 

In the next two words of the structure, the horizontal (HorizPot) and 
vertical ( VertPot) position of sliders are stored. A value of zero means left 
or upper, while the value $FFFF means right or lower. The value that 
results from movement is in this range. You set these values to zero at 
the start of the program. After moving the mouse, there is different values 
here. 

dew 0,0 ;X- and Y-position of slider 

Next come two words which determine the size of the AUTOKNOB or 
the step size of the slider (this determines how far the slider moves when 
you click in the box next to the slider). These words are called HorizBody 
(horizontal movement) and VertBody (vertical movement). 

dew $ffff/16 jHorizontal step size: 1/16 

dew :No vertical movement 

;The next six words are initialized by Intuition. 



dew 





;Box width 


dew 





JBox height 


dew 





jAbsolute step size horizontal 


dew 





;And vertical 


dew 





jLeft border of box 


dew 





;Upper border of box 



That's it. Here's a quick overview of the Proplnfo structure: 



propinf o: 






dew 


2 


JFlags: FREEHORIZ 


dew 


0,0 


;X- and Y-position of slider 


dew 


$ffff/16 


jHorizontal step size: 1/16 


dew 





JNo vertical movement 


dew 





JBox width 


dew 





JBox height 


dew 





jAbsolute step size horizontal 


dew 





;and vertical 


dew 





JLeft border of box 


dew 





jUpper border of box 



Once you've typed this in, you can start the program and try it out. 

You can also try vertical movement by setting the flag word equal to six, 
the vertical step size to $FFFF/10, and the height of the gadget to 80, for 
example. To try out the AUTOKNOBs, change the flag value to seven. 
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Here is a complete example program using what you have learned in this 
chapter: 

; 7_Intuition.asm 

;** Demo-Program for working with Intuition ** 



movescreen 


= 


-162 


openscreen 


= 


-198 


closescreen 


= 


-66 


openwindow 


= 


-204 


closewindow 


= 


-72 


autorequest 


= 


-348 


SetMenuStrip 


= 


-264 


ClearMenuStrip 


= 


-54 


PrintlText 


= 


-216 


Drawlmage 


= 


-114 


DrawBorder 


= 


-108 


DisplayBeep 


= 


-96 


closelibrary 


= 


-414 


openlib 


= 


-408 


execbase 


= 


4 


GetMsg 


= 


-372 


joy2 


= 


$dff0c 


fire 


= 


$bfe001 



;! ! ! when > 500KB ! ! ! 

;org $40000 

;load $40000 

; or use AssemPro to place in CHIP RAM 

• t i i i t t t i t t t t i i i t t t t t 



bsr 


openint 


bsr 


scropen 


bsr 


windopen 


bsr 


setmenu 


bsr 


print 


lea 


border, al 


move 


#22,d0 


move 


#30,dl 


bsr 


borderdraw 


bsr 


draw 


bsr 


request 
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loop: 





move.l 


execbase,a6 








move.l 


windowhd,aO 








move.l 


86(a0) ,a0 


;User-Port 






jsr 


GetMsg(a6) 








tst.l 


dO 








beq 


loop 


;no event 






move.l 


dO,aO 








move.l 


$16 (aO) ,msg 


jEvent: LO=Item, HI=Even 


t 




move.l 


msg,d6 


;to test 






move.l 


d6,d7 








lsr 


#8,d7 








lsr 


#3,d7 


;Sub menu point in D7 






clr.l 


d5 








roxr 


#l,d6 








roxl 


#l,d5 


JMenu number in D5 






and.l 


#$7f,d6 








cmp 


#$7f,d6 


;no menu point ? 






beq 


loop 


;no: continue 






lsr 


#4,d6 


JMenu point in D6 






cmp 


#l,d6 


jPoint 2 ? 






bne 


nol 








move.l 


intbase,a6 








move.l 


screenhd,aO 








jsr 


DisplayBeep (a6) 






nol: 


cmp 
bne 


#0,d6 
loop 






ende: 


bsr 
bsr 
bsr 
bsr 

rts 


clearmenu 
windclose 
scrclose 
closeint 






openint: 










move.l 


execbase,a6 








lea 


intname,al 








jsr 


openlib (a6) 








move.l 


dO,intbase 








rts 









closeint : 

move.l execbase,a6 

move.l intbase,al 

jsr closelibrary (a6) 

rts 



scropen: 




move.l 


intbase,a6 


lea 


screen defs,aO 


jsr 


openscreen (a6) 


move.l 


dO,screenhd 


rts 
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scrclose: 

move.l intbase,a6 
move.l screenhd,aO 
jsr closescreen (a6) 

rts 



scrmove: 



move.l intbase,a6 

move.l screenhd,aO 

jsr movescreen (a6) 

rts 



windopen: 

move.l 

lea 

jsr 

move.l 

rts 



intbase,a6 
windowdef,aO 
openwindow(a6) 
dO,windowhd 



windclose: 

move.l intbase,a6 
move.l windowhd,aO 
jsr closewindow (a6) 

rts 



request: 




move.l 


windowhd,aO 


lea 


btext,al 


lea 


ltext,a2 


lea 


rtext,a3 


move.l 


#0,d0 


move.l 


#0,dl 


move.l 


#180,d2 


move.l 


#80,d3 


move.l 


intbase,a6 


jsr 


autorequest (a6) 


rts 




setmenu: 




lea 


mentab,aO 


lea 


menu,al 


move 


#10,dl 


menuloop: 




clr.l 


d2 


move.l 


al,a2 


tst.l 


(aO) 


beq 


setmenul 


clr.l 


(al) + 


move 


dl,(al) + 


add.l 


#70,dl 


move.l 


#50,(al) + 


move.l 


#$a0001,(al) + 


move.l 


(aO) +,(al) + 


lea 


12 (al),a3 



jPointer to text pointer in AO 
;Pointer to Menu field in Al 
;Menu position=10 



;Menu point-Y =0 
JSave pointer 



;End 



move.l a3, (al) + 



;Menu title 
;Menu point 
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clr.l 


(al) + 




clr.l 


(al) + 




itemloop: 






tst.l 


(aO) 


Jiast one ? 


beq 


menuend 


;yes 


lea 


54(al),a3 




move.l 


a3,(al) + 


jPointer to next Point 


move.l 


d2,(al) + 


;x/y 


add 


#10,d2 




move.l 


#$5a000a,(al) + 


jwidth/height 


move 


#$52,(al) + 




clr.l 


(al) + 




lea 


16(al),a3 




move.l 


a3,(al) + 


JText structor-pointe: 


clr.l 


(al) + 




clr.l 


(al) + 




clr.l 


(al) + 




move 


#$l,(al) + 


JText-Structor set 


clr 


(al) + 




move.l 


#$50003, (al) + 




clr.l 


(al) + 




move.l 


(a0)+,(al) + 


;Text-pointer 


clr.l 


(al) + 




bra 


itemloop 


Jnext Point... 


menuend: 






clr.l 


-54(al) 




tst.l 


(a0) + 




tst.l 


(aO) 


Jstill in Menu ? 


beq 


setmenul 


;no: ready 


move.l 


al,(a2) 


jPointer to next menu 


bra 


menuloop 


Jand continue 


setmenul: 






move.l 


intbase,a6 




move.l 


windowhd,aO 




lea 


menu,al 




jsr 


SetMenuStrip(a6) 




rts 







clearmenu: 

move.l intbase,a6 

move.l windowhd,aO 

jsr ClearMenuStrip (a6) 

rts 



print: 



move.l 

move.l 

move.l 

lea 

move.l 

move.l 



intbase,a6 
windowhd,aO 
50(a0),a0 
ggtext,al 
#30,d0 ;x 
#16,dl ;Y 
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Dsr 


PrintlText (a6) 


rts 




draw: 




move.l 


intbase,a6 


move.l 


windowhd,aO 


move.l 


50(aO),aO 


lea 


image, al 


move.l 


#200,d0 


move.l 


#100,dl 


jsr 


Drawlmage (a6) 


rts 




borderdraw: 




move.l 


intbase,a6 


move.l 


windowhd,aO 


move.l 


50(aO),aO 


jsr 


DrawBorder (a6) 


rts 




screen defs: 




dew 


0,0 


dew 


640,200 


dew 


4 


dc.b 





dc.b 


1 


dew 


$800 


dew 


15 


del 





del 


titel 


del 





del 





windowdef : 




dew 


10,20 


dew 


300,150 


dc.b 


0,1 


del 


$300 


del 


$100f 


del 


gadget 


del 





del 


windname 


screenhd: del 


del 





dew 


200,40,600,200 


dew 


$f 


btext: 




deb 


3,3 


dc.b 





align 


dew 10,10 


del 





del 


bodytxt 


del 






bodytxt: dc.b n Requester-Text n ,0 
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ltext: 



align 

dc.b 

dc.b 

align 

del 

del 

del 



3,1 



dew 5,3 



lefttext 





lefttext: deb 
align 



rtext: 



deb 
deb 

align 
del 
del 
del 



"left",0 



0,1 



dew 5,3 



righttext 





righttext: deb "right", 

align 
titel: dc.b 
windname: deb 

align 
intbase: del 
intname: deb 

align 
mentab: 



"User Screen", 
"Window-Title", 
windowhd: del 


"intuition.library",0 
msg: del 



del menul 

del mp 1 1 ,mp 1 2 ,mp 1 3 ,mp 1 4 ,mp 1 5 ,mp 1 6,mp 1 7 ,mp 1 8 ,mp 19,0 

del menu2 

del mp21,mp22,mp23,0 

del menu3 

del mp31,mp32,0 

del menu4,mp41,0 

del 



menul: 

mpll: 

mpl2: 

mpl3: 

mpl4: 

mpl5: 

mpl6: 

mpl7: 

mpl8: 

mpl9: 



deb 
dc.b 
deb 
deb 
deb 
deb 
deb 
deb 
deb 
deb 



"Menu 1",0 
•Point 11", 
•Point 12", 
"Point 13", 
•Point 14", 
•Point 15", 
•Point 16", 
•Point 17", 
•Point 18", 
•Point 19", 



menu2: 
mp21: 
mp22: 
mp23: 



deb 
dc.b 
deb 
deb 



"Menu 2",0 
"End ! ",0 
"Beep",0 
"Point 23", 



menu3: dc.b 
mp31: deb 
mp32: deb 



"Menu 3",0 
"Point 31", 
"Point 32", 
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menu4: 


dc.b 


"Menu 4 ",0 


mp41: 


dc.b 

align 


"Point 41", 


gadget 








del 


gadget 1 




dew 


20,80,80,10 




dew 







dew 


$2 




dew 


4 




del 


border 




del 







del 







del 







del 


strinfo 




dew 


2 




del 





border 








dew 


0,0 




dc.b 


1,0,0 




dc.b 


5 




del 


koord 




del 






;Activation, $802 for Longlnt 



;XY-Pair 



koord: 



dew -2,-2,8 0,-2,8 0,9,-2,9,-2,-2 



strinfo: 






del 


strpuf fer 




del 


undo 




dew 





;Cursor-Position 


dew 


10 


;max. Char 


dew 







dew 


0,0,0,0,0 




del 


0,0,0 




strpuf f er: dc 


b "Hello !", 0,0,0 




undo: del 


0,0,0 




align 






gadgetl: 






del 


gadget 2 


;more Gadget 


dew 


40,50,32,13 




dew 


$6 


;Flags: invert 


dew 


$103 


;Activate 


dew 


1 


;Gadget-Type 


del 


image 


jGadget-Image 


del 


image2 


;Select -Gadget 


del 


ggtext 


;Gadget-Text 


del 





;no Exclude 


del 





;special Info 


dew 


1 


;id 


del 





;UserData 


ggtext: 







deb 1,0,1 

align dew -8,1 4 
del 
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del 


swtext 




del 





swtext 


Idcb 


"Switch", 




alig 


n 


image: 








dew 


0,0 




dew 


32,13 




dew 


1 




del 


imgdata 




deb 


2,1 




del 





image2: 








dew 


0,0 




dew 


32,13 




dew 


1 




del 


imgdata2 




deb 


2,1 




del 





imgdat. 


a: 






del 







del %000000000 11 10000000 000 000000000 




del %000000001 11 11 00000 11 10 100 100000 




del %000000001 11 11000001 0101 101000000 




del %0000000001111000001010101 1000000 




del %00000000000111 00001 1101001000000 




del %0000000000001 1100000000000000000 




del %00000000000001 11000000 0000000 000 




del %00000000000111 11 11 11 100000000000 




del %00000000001 11 111 111 111 0000000000 




del %00000000001111111111110000000000 




del %000000000001 1000000 11 00000000000 




del 





imgdat. 


a2: 






del 







del 


%0000000000000000000011 100000 00 00 




del 


%0001 11 01 1101 1100000 111 11 000000 00 




del 


%000 10 10 100010000000 111 11 0000 0000 




del 


%00010 101 1001 100 00001 11 100000 00 00 




del 


%0001 11010001000000 11 10000 000 00 00 




del 


%000000000000000001 11000000000000 




del 


%000000000000000011 10000000000000 




del 


%00000 00000011111111110000000 0000 




del 


%000000000011111111 11110000000000 




del 


%000000000011111111 11110000000000 




del 


%000000000001 100000 01 10000000 0000 




del 





gadget2: 






del 







dew 


150,30,100,50 




dew 


5 




dew 


2 




dew 


3 ;Prop. Gadget 




del 


mover Jborder 
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del 


0,0,0 


del 


specinfo 


dew 


3 


del 





specinf o: 




dew 


6 


dew 


0,0 


dew 


$ffff/10,$ffff/5 


dew 


0,0,0,0,0,0 


mover: 




dew 


0,0,16,7 


dew 


1 


del 


moverdata 


deb 


1,0 


del 






JFlags: free horiz 



moverdata: 

dew %01 11111 111111110 
dew%0101111111111010 
dew %01 0101 11 111 010 10 
dew %01 01 01 01 101010 10 
dew %01 0101 11 111010 10 
dew %01 011111 11111010 
dew %01 11 111 11 11 111 10 



menu: blk.w 



500 



end 



227 



Chapter 8 

Advanced 
Programming 



Abacus g. Example Programs 



8 Advanced Programming 



You've learned a lot about machine language programming on the 
Amiga. What you need yet are a few routines that can be used as pro- 
gramming tools. We'll work on that right now. They'll be easy to use in 
your own program. The sky's the limit now! 



8.1 Supervisor Mode 



As mentioned in the chapter on the MC68000 processor, there are two 
operating modes: the User and the Supervisor mode. It is often necessary 
to move between the two modes. However, this isn't a simple process. 

The reason you want to do this, is that in User mode, you can't access the 
Status registers. If you write to one of them, an Exception is executed 
which crashes the program. 

How can you get into Supervisor mode? 

No problem. The operating system of the Amiga contains a function in 
the EXEC library that lets you get into the Supervisor mode. It's called 
Superstate and it doesn't need any parameters. You can easily call this 
program by using the following lines: 

ExecBase = 4 ;EXEC base address 

Superstate =-150 ;Turn on function 

move.l ExecBase, a6 ;EXEC base address in A6 
jsr Superstate (a6) ;Turn on Supervisor mode 
move.l d0,savesp ;Save return value 

savesp: blk.l 1 ;Space for SP value 

You get the value of the Stack Pointer (SP) back in the DO register. 
You'll also find it in register A7, but this register is changed regularly. 
The reason is that in Supervisor mode, the Amiga works with all the 
Interrupts and with the SP, and there are lots of Interrupts for this com- 
puter. We'll talk about Interrupts in a bit. 
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After this call, you'll use the User stack instead of the Supervisor stack. 
In this way, you can access the old User stack. You need to make sure 
that the User stack is large enough since the Interrupts must have enough 
room for their data on the stack. 

You need to save the value returned in DO, because you'll need this value 
later. You need to return to User mode sometime. There's a function for 
this in the EXEC library as well. It is called the UserState function. It 
needs one parameter, the SP value that comes back from the Superstate 
function. 

Since you've saved this value in the long word starting at "savesp", you 
can write the following: 

UserState = -156 

move.l ExecBase,a6 JEXEC base address in A6 
move.l savesp,dO ;Put old SP in DO 
jsr UserState (a6) ;Return to User mode 

Now you are back in the User mode. The User Stack Pointer (USP) is the 
same as before. You can write functions that need to be ran from the 
Supervisor mode as subroutines. First you call Superstate, save the 
return value, execute the desired function, call UserState, and end with a 
RTS command. If the USP was changed, the RTS command wouldn't 
work right, and the computer would jump who know's where and perhaps 
crash. Here it works though. 

Now comes the question: how does the operating system get into Super- 
visor mode? That's not too difficult; it goes like this: 

The Superstate function attempts to access a Status Register. This causes 
an Exception to occur and a routine is called whose address begins at the 
long word starting at $20. It is the Exception Vector for Privilege Viola- 
tion. The routine that it branches to is called in Supervisor mode. Then it 
tests where this Exception came from. If the routine finds that the Excep- 
tion comes from the Superstate routine whose address it knows, the 
matter is settled. It just branches to the routine without turning off the 
User mode. That's all there is to it 
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8.2 Exception programming 

The exceptions described in the processor chapter offer you a lot of oppor- 
tunities to control the Amiga's functions. You can use them to specify 
how errors should be handled and even list a crashed program. 

Here is a list of vectors that are used to jump to the Exception routines: 
Number Address Use with 



2 


$008 


Bus Error 


3 


$00C 


Address Error 


4 


$010 


Illegal command 


5 


$014 


Division by zero 


6 


$018 


CHK command 


7 


$01C 


TRAPV command 


8 


$020 


Privilege Violation 


9 


$024 


Trace 


10 


$028 


Axxx command emulation 


11 


$02C 


Fxxx command emulation 




$030-$038 


Reserved 


15 


$03C 


Uninitialized Interrupt 




$040-$05F 


Reserved 


24 


$060 


Unauthorized Interrupt 


25-31 


$064-$083 


Level 1-7 Interrupt 


32^7 


$080-$0BF 


TRAP commands 




$0C0-$0FF 


Reserved 


64-255 


$100-$3FF 


User Interrupt vector 



Let's look at the TRAP commands as an example. They aren't used in the 
Amiga operating system. A TRAP command and a number between zero 
and fifteen are used to call one of 16 possible TRAP routines. If the com- 
mand TRAP #0 is executed, the processor (in Supervisor mode) branches 
to the routine whose address lies at $80 in memory. This routine must 
end with a RTE (ReTurn from Exception) command. 

Some operating systems, for example, the ATARI ST's TOS operating 
systems, are completely callable via these TRAPs. Parameters are put on 
the stack, and then a TRAP command is executed. The advantage is that 
you don't have to know any of the operating system addresses. In the 
Amiga you must know the addresses (ExecBase = 4). 

Let's write your own TRAP routine to demonstrate the use of the TRAP 
command. You'll need three program sections: 
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1. The initialization of the TRAP vector. 

2. The TRAP routine itself. (It must end with RTE.) 

3. A test routine that calls the TRAP command. 

Initialization is very short: 



init: 



move.l #trap0,$80 
rts 



;Set vector for TRAP #0 



Now you need to write the trapO routine. Let's use the example from the 
hardware chapter that produced a beep. 

Let's write this routine using as little effort as possible. Change the RTS 
to a RTE at the end, erase the line in which the loop counter DO was 
loaded for the tone production, and change the loop so that it works with 
long words. Now you can load the register with an arbitrary value and 
have the TRAP #0 followed by a peep of arbitrary duration. 



•* * 


Beep tone production 


after a TRAP #0 ** 


ctlw 


= $dff096 


JDMA control 


cOthi 


= $df f 


aO 


;HI table address 


cOtlo 


= cOthi + 2 


;LO table address 


cOtl 


= cOthi 


+ 4 


jTable length 


cOper 


= cOthi 


+ 6 


;Read in rate 


cOvol 


= cOthi + 8 


;Volume 


trapO: 






;* Produce a short peep 




move.l 


#table,cOthi 


;Table beginning 




move 


#4,c0tl 


;Table length 




move 


#300,c0per 


;Read in rate 




move 


#40,c0vol 


;Volume 




move 


#$8201,ctlw 


;Start DMA (sound) 



loop: 



still: 



table: 



subq. 1 


#l,d0 


;Counter-l 


bne 


loop 


;Count down to 


move 


#l,ctlw 


jTurn on tone 


rte 




JException end 
;Sound table 


dc.b 


-40,-70, 


-40,0,40,70,40,0 



You need to make sure that "table" is in Chip RAM ($00000-$7FFFF), 
otherwise the Sound Chip can't access the data! 

After entering this, you can test it out using the following routine: 



test: 



move.l #$2ffff,d0 

trap #0 

rts 



;Pass tone length in DO 
;Carry out Exception: peep 
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Now assemble both routines and start the initialization routine, init. 
Nothing happens. 

Start the second routine, test. A beep that lasts about one second is out- 
put. 

One thing you must keep in mind is that if you change the program and 
reassemble it, the address of the trapO routine can change. Before you 
execute the TRAP command, you must repeat the initialization, so that 
the computer doesn't jump to the wrong location! 
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Appendix 



Overview of Library Functions 



The following table gives you an overview of the available libraries and 
their functions. Each sublist of functions is preceded by the name of the 
library it is found in. 

These functions are listed with their negative offset in hex and decimal. 
Their name and their parameters are also specified. The parameter names 
are in parenthesis behind the function name. The second set of parenthesis 
includes a list of registers that correspond to the parameter names. If no 
parameters are needed, we put () to let you know. 



clist. library 



$001E 


-30 


$0024 


-36 


$002A 


-42 


$0030 


-48 


$0036 


-54 


$003C 


-60 


$0042 


-66 


$0048 


-72 


$004E 


-78 


$0054 


-84 


•$005A 


-90 


$0060 


-96 


$0066 


-102 


■$006C 


-108 


$0072 


-114 


$0078 


-120 


■$007E 


-126 


•$0084 


-132 


■$008A 


-138 


■$0090 


-144 


■$0096 


-150 


■$009C 


-156 



InitCLPool (cLPool, size) (A0,D0) 

AllocCList (cLPool) (Al) 

FreeCList (cList) (A0) 

FlushCList (cList) (A0) 

SizeCList (cList) (A0) 

PutCLChar (cList,byte) (A0,D0) 

GetCLChar (cList) (A0) 

UnGetCLChar (cList,byte) (A0,D0) 

UnPutCLChar (cList) (A0) 

PutCLWord (cList,word) (A0,D0) 

GetCLWord (cList) (A0) 

UnGetCLWord (cList,word) (A0,D0) 

UnPutCLWord (cList) (A0) 

PutCLBuf (cList,buffer, length) (A0,A1,D1) 

GetCLBuf (cList,buf fer,maxLength) (A0,A1,D1) 

MarkCList (cList.of f set) (A0,D0) 

IncrCLMark (cList) (A0) 

PeekCLMark (cList) (A0) 

SplitCList (cList) (A0) 

CopyCList (cList) (A0) 

SubCList (cList,index,length) (A0,D0,D1) 

ConcatCList (sourceCList,destCList ) (A0,A1) 



console. library 



-$002A -42 CDInputHandler (events,device) (A0,A1) 

-$0030 -48 RawKeyConvert (events, buf f er,length,keyMap) 

(A0,A1,D1,A2) 



diskfont. library 



-$001E -30 OpenDiskFont (textAttr) (A0) 

-$0024 -36 AvailFonts (buf fer,buf Bytes, flags) (A0,D0,D1) 
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dos. library 



$001E 


-30 


$0024 


-36 


$002A 


-42 


$0030 


-48 


$0036 


-54 


$003C 


-60 


$0042 


-66 


$0048 


-72 


$004E 


-78 


$0054 


-84 


$005A 


-90 


$0060 


-96 


$0066 


-102 


$006C 


-108 


$0072 


-114 


$0078 


-120 


$007E 


-126 


$0084 


-132 


•$008A 


-138 


$0090 


-144 


$0096 


-150 


■$009C 


-156 


•$00A2 


-162 


$00A8 


-168 


■$00AE 


-174 


■$00B4 


-180 


■$00BA 


-186 


■$00C0 


-192 


■$00C6 


-198 


■$oocc 


-204 


■$00D2 


-210 


■$00D8 


-216 


■$00DE 


-222 



Open (name,accessMode) (D1,D2) 

Close (file) (Dl) 

Read (f ile.buf fer.length) (D1,D2,D3) 

Write (file,buffer,length) (D1,D2,D3) 

Input () 

Output () 

Seek <file,position,of f set) (D1,D2,D3) 

DeleteFile (name) (Dl) 

Rename (oldName,newName) (D1,D2) 

Lock (name,type) (D1,D2) 

UnLock (lock) (Dl) 

DupLock (lock) (Dl) 

Examine (lock,f ilelnf oBlock) (D1,D2) 

ExNext (lock,fileInfoBlock) (D1,D2) 

Info (lock,parameterBlock) (D1,D2) 

CreateDir (name) (Dl) 

CurrentDir (lock) (Dl) 

IoErr () 

CreateProc (name,pri,segList,stackSize) (D1,D2,D3,D4 ) 

Exit (returnCode) (Dl) 

LoadSeg (fileName) (Dl) 

UnLoadSeg (segment) (Dl) 

GetPacket (wait) (Dl) 

QueuePacket (packet) (Dl) 

DeviceProc (name) (Dl) 

SetComment (name, comment) (D1,D2) 

SetProtection (name,mask) (D1,D2) 

DateStamp (date) (Dl) 

Delay (timeout) (Dl) 

WaitForChar (f ile,timeout ) (D1,D2) 

ParentDir (lock) (Dl) 

Islnteractive (file) (Dl) 

Execute (string,f ile,f ile) (D1,D2,D3) 



exec. library 



$001E 


-30 


$0024 


-36 


$002A 


-42 


$0030 


-48 


$0036 


-54 


$003C 


-60 


$0042 


-66 


$0048 


-72 


$004E 


-78 


$0054 


-84 



-$005A 

-$0060 
-$0066 
-$006C 
-$0072 



-90 

-96 

-102 
-108 
-114 



Supervisor () 
Exitlntr () 
Schedule () 
Reschedule ( ) 
Switch () 
Dispatch ( ) 
Exception () 

InitCode (startClass,version) (D0,D1) 
InitStruct (initTable,memory,size) (A1,A2,D0) 
MakeLibrary ( funclnit, struct In it, libl nit, dataSize, 
codeSize) ( A0,A1,A2,D0,D1 ) 

MakeFunctions (target,f unction Array, fun cDispBase) 
(A0,A1,A2) 

FindResident (name) (Al) 
InitResident (resident, segList) (A1,D1) 
Alert (alertNum,parameters) (D7,A5) 
Debug () 
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-$0078 


-120 


-$007E 


-126 


-$0084 


-132 


-$008A 


-138 


-$0090 


-144 


-$0096 


-150 


-$009C 


-156 


-$00A2 


-162 


-$00A8 


-168 


-$00AE 


-174 


-$00B4 


-180 


-$00BA 


-186 


-$00C0 


-192 


-$00C6 


-198 


-$oocc 


-204 


-$00D2 


-210 


-$00D8 


-216 


-$00DE 


-222 


-$00E4 


-228 


-$00EA 


-234 


-$00F0 


-240 


-$00F6 


-246 


-$00FC 


-252 


-$0102 


-258 


-$0108 


-264 


-$010E 


-270 


-$0114 


-276 


-$011A 


-282 


-$0120 


-288 


-$0126 


-294 


-$012C 


-300 


-$0132 


-306 


-$0138 


-312 


-$013E 


-318 


-$0144 


-324 


-$014A 


-330 


-$0150 


-336 


-$0156 


-342 


-$015C 


-348 


-$0162 


-354 


-$0168 


-360 


-$016E 


-366 


-$0174 


-372 


-$017A 


-378 


-$0180 


-384 


-$0186 


-390 


-$018C 


-396 


-$0192 


-402 


-$0198 


-408 


-$019E 


-414 


-$01A4 


-420 


-$01AA 


-426 


-$01B0 


-432 


-$01B6 


-438 


-$01BC 


-444 


-$01C2 


-450 



Disable () 

Enable () 

Forbid () 

Permit () 

SetSR (newSR,mask) (D0,D1) 

Superstate () 

UserState (sysStack) (DO) 

SetlntVector (intNumber, interrupt ) (D0,A1) 

AddlntServer (intNumber, interrupt) (D0,A1) 

RemlntServer (intNumber, interrupt ) (D0,A1) 

Cause (interrupt) (Al) 

Allocate (f reeList,byteSize) (A0,D0) 

Deallocate (f reeList,memoryBlock,byteSize) (A0,A1,D0) 

AllocMem (byteSize, requirements) (D0,D1) 

AllocAbs (byteSize,location) (D0,A1) 

FreeMem (memoryBlock, byteSize) (A1,D0) 

AvailMem (requirements) (Dl) 

AllocEntry (entry) (A0) 

FreeEntry (entry) (A0) 

Insert (list,node,pred) (A0,A1,A2) 

AddHead (list,node) (A0,A1) 

AddTail (list,node) (A0,A1) 

Remove (node) (Al) 

RemHead (list) (A0) 

RemTail (list) (A0) 

Enqueue (list, node) (A0,A1) 

FindName (list, name) (A0,A1) 

AddTask (task,initPC,f inalPC) (A1,A2,A3) 

RemTask (task) (Al) 

FindTask (name) (Al) 

SetTaskPri (task,priority) (A1,D0) 

SetSignal (newSignals,signalSet ) (D0,D1) 

SetExcept (newSignals,signalSet ) (D0,D1) 

Wait (signalSet) (DO) 

Signal (task, signalSet ) (A1,D0) 

AllocSignal (signalNum) (DO) 

FreeSignal (signalNum) (DO) 

AllocTrap (trapNum) (DO) 

FreeTrap (trapNum) (DO) 

AddPort (port) (Al) 

RemPort (port) (Al) 

PutMsg (port,message) (A0,A1) 

GetMsg (port) (A0) 

ReplyMsg (message) (Al) 

WaitPort (port) (A0) 

FindPort (name) (Al) 

AddLibrary (library) (Al) 

RemLibrary (library) (Al) 

OldOpenLibrary (libName) (Al) 

CloseLibrary (library) (Al) 

SetFunction (library, f uncOf f set,f uncEntry) (A1,A0,D0) 

SumLibrary (library) (Al) 

AddDevice (device) (Al) 

RemDevice (device) (Al) 

OpenDevice (devName, unit, ioRequest, flags) (A0,D0,A1,D1 ) 

CloseDevice (ioRequest) (Al) 
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DoIO (ioRequest) (Al) 

SendIO (ioRequest) (Al) 

ChecklO (ioRequest) (Al) 

WaitIO (ioRequest) (Al) 

AbortIO (ioRequest) (Al) 

AddRescource (rescource) (Al) 

RemRescource (rescource) (Al) 

OpenRescource (resName, version) (A1,D0) 

RawIOInit () 

RawMayGetChar () 

RawPutChar (char) (DO) 

RawDoFmt () (A0,A1,A2,A3) 

GetCC () 

TypeOfMem (address) (Al) 

Procedure (semaport,bidMsg) (A0,A1) 

Vacate (semaport) (AO) 

OpenLibrary (libName, version) (A1,D0) 



-$01C8 


-456 


-$01CE 


-462 


-$01D4 


-468 


-$01DA 


-474 


-$01E0 


-480 


-$01E6 


-486 


-$01EC 


-492 


-$01F2 


-498 


-$01F8 


-504 


-$01FE 


-510 


-$0204 


-516 


-$020A 


-522 


-$0210 


-528 


-$0216 


-534 


-$021C 


-540 


-$0222 


-546 


-$0228 


-552 



graphics. library 



-$001E -30 BltBitMap (srcBitMap,srcX,srcY,destBitMap,destX,destY, 

sizeX,sizeY,minterm,mask,tempA) 

(A0,D0,D1,A1,D2,D3,D4,D5,D6,D7,A2) 
-$0024 -36 BltTemplate (source. srcX.srcMod.destRastPort.destX. 

destY,sizeX,sizeY) (A0,D0,D1,A1,D2,D3,D4,D5) 

ClearEOL (rastPort) (Al) 

ClearScreen (rastPort) (Al) 

TextLength (RastPort, string,count) (A1,A0,D0) 

Text (RastPort,String,count) (A1,A0,D0) 

SetFont (RAstPortID,textFont ) (A1,A0) 

OpenFont (textAttr) (A0) 

CloseFont (textFont) (Al) 

AskSoftStyle (rastPort) (Al) 

SetSoftStyle (rastPort, style,enable) (A1,D0,D1) 

AddBob (bob,rastPort) (A0,A1) 

AddVSprite (vSprite, rastPort ) (A0,A1) 

DoCollision (rastPort) (Al) 

DrawGList (rastPort,viewPort ) (A1,A0) 

InitGels ( dummyHead,dummy Tail, Gels In f o) (A0,A1,A2) 

InitMasks (vSprite) (A0) 

RemlBob (bob,rastPort,viewPort ) (A0,A1,A2) 

RemVSprite (vSprite) (A0) 

SetCollision (type, routine, gelslnfo) (D0,A0,A1) 

SortGList (rastPort) (Al) 

AddAnimObj (ob j,animationKey, rastPort ) (A0,A1,A2) 

Animate (animationKey,rastPort ) (A0,A1) 

etGBuf fers (animationOb j,rastPort,doubleBuf f er ) 

(A0,A1,D0) 

InitGMasks (animationOb j) (A0) 

GelsFuncE () 

GelsFuncF () 

LoadRGB4 (viewPort, colors, count ) (A0,A1,D0) 

InitRastPort (rastPort) (Al) 

InitVPort (viewPort) (A0) 

MrgCop (view) (Al) 



$002A 


-42 


$0030 


-48 


$0036 


-54 


$003C 


-60 


$0042 


-66 


$0048 


-72 


•$004E 


-78 


$0054 


-84 


■$005A 


-90 


■$0060 


-96 


$0066 


-102 


$006C 


-108 


$0072 


-114 


$0078 


-120 


■$007E 


-126 


■$0084 


-132 


■$008A 


-138 


■$0090 


-144 


$0096 


-150 


■$009C 


-156 


■$00A2 


-162 


■$00A8 


-168 


■$00AE 


-174 


$00B4 


-180 


■$00BA 


-186 


■$00C0 


-192 


■$00C6 


-198 


■$oocc 


-204 


■$00D2 


-210 
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MakeVPort (view,viewPort) (A0,A1) 
LoadView (view) (Al) 
WaitBlit () 

SetRast (rastPort,color) (A1,D0) 
Move (rastPort,x,y) (A1,D0,D1) 
Draw (rastPort,x,y) (A1,D0,D1) 
AreaMove (rastPort,x,y) (A1,D0,D1) 
AreaDraw (rastPort,x,y) (A1,D0,D1) 
AreaEnd (rastPort) (Al) 
WaitTOF () 
QBlft (blit) (Al) 

I nit Area (areaInfo,vectorTable,vectorTableSize) 
(A0,A1,D0) 

SetRGB4 (viewPort,index,r,g,b) (A0,D0,D1,D2,D3) 
QBSBlit (blit) (Al) 

BltClear (memory,size, flags) (A1,D0,D1) 
RectFill (rastPort,xl,yl,xu,yu) (A1,D0,D1,D2,D3) 
Bit Pat tern (rastPort,ras,xl,yl,maxX,maxY,f illBytes) 
(A1,A0,D0,D1,D2,D3,D4) 
ReadPixel (rastPort, x, y) (A1,D0,D1) 
WritePixel (rastPort,x, y) (A1,D0,D1) 
Flood (rastPort,mode,X,y) ( A1,D2,D0,D1) 
PolyDraw (rastPort, count,polyTable) (A1,D0,A0) 
SetAPen (rastPort,pen) (A1,D0) 
SetBPen (rastPort,pen) (A1,D0) 
SetDrMd (rastPort,drawMode) (A1,D0) 
InitView (view) (Al) 
CBump (copperList) (Al) 

CMove (copperList, destination,data) (A1,D0,D1) 
CWait (copperList, x,y) (A1,D0,D1) 
VBeamPos () 

InitBitMap (bitMap,depth,width,heigth) ( A0,D0,D1,D2 ) 
ScrollRaster ( rastPort, dX,dY,minx,miny,maxx,maxy) 
(A1,D0,D1,D2,D3,D4,D5) 
WaitBOVP (viewport) (AO) 
GetSprite (simpleSprite,num) (A0,D0) 
FreeSprite (num) (DO) 

ChangeSprite (vp,simpleSprite,data) (A0,A1,A2) 
MoveSprite (viewPort,simpleSprite,x,y) (A0,A1,D0,D1) 
LockLayerRom (layer) (A5) 
UnlockLayerRom (layer) (A5) 
SyncSBitMap (1) (AO) 
CopySBitMap (11,12) (A0,A1) 
OwnBlitter () 
DisownBlitter () 

InitTmpRas (tmpras.buf f,size) (A0,A1,D0) 
AskFont (rastPort, textAttr) (A1,A0) 
AddFont (textFont) (Al) 
RemFont (textFont) (Al) 
AllocRaster (width,heigth) (D0,D1) 
FreeRaster (planeptr,width,heigth) (A0,D0,D1) 
AndRectRegion (rgn,rect) (A0,A1) 
OrRectRegion (rgn,rect) (A0,A1) 
NewRegion () 
** reserved ** 
ClearRegion (rgn) (AO) 



-$00D8 


-216 


-$00DE 


-222 


-$00E4 


-228 


-$00EA 


-234 


-$00F0 


-240 


-$00F6 


-246 


-$00FC 


-252 


-$0102 


-258 


-$0108 


-264 


-$010E 


-270 


-$0114 


-276 


-$011A 


-282 


-$0120 


-288 


-$0126 


-294 


-$012C 


-300 


-$0132 


-306 


-$0138 


-312 


-$013E 


-318 


-$0144 


-324 


-$014A 


-330 


-$0150 


-336 


-$0156 


-342 


-$015C 


-348 


-$0162 


-354 


-$0168 


-360 


-$016E 


-366 


-$0174 


-372 


-$017A 


-378 


-$0180 


-384 


-$0186 


-390 


-$018C 


-396 


-$0192 


-402 


-$0198 


-408 


-$019E 


-414 


-$01A4 


-420 


-$01AA 


-426 


-$01B0 


-432 


-$01B6 


-438 


-$01BC 


-444 


-$01C2 


-450 


-$01C8 


-456 


-$01CE 


-462 


-$01D4 


-468 


-$01DA 


-474 


-$01E0 


-480 


-$01E6 


-486 


-$01EC 


-492 


-$01F2 


-498 


-$01F8 


-504 


-$01FE 


-510 


-$0204 


-516 


-$020A 


-522 


-$0210 


-528 
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$0216 


-534 


$021C 


-540 


$0222 


-546 


$0228 


-552 


$022E 


-558 


$0234 


-564 


$023A 


-570 


$0240 


-576 


$0246 


-582 


$024C 


-588 


$0252 


-594 


$0258 


-600 



-$025E 



-606 



DisposeRegion (rgn) (A0) 

FreeVPortCopLists (viewport) (A0) 

FreeCopList (coplist) (A0) 

ClipBlit (srcrp,srcX,srcY,destrp,destX,destY,sizeX, 

sizeY.minterm) ( A0,D0,D1,A1,D2,D3,D4,D5,D6) 

XorRectRegion (rgn, rect ) (A0,A1) 

FreeCprList (cprlist) (A0) 

GetColorMap (entries) (DO) 

FreeColorMap (colormap) (A0) 

GetRGB4 (colormap,entry) (A0,D0) 

ScrollVPort (vp) (A0) 

UCopperListlnit (copperlist.num) (A0,D0) 

FreeGBuf fers (animationOb j,rastPort, 

doubleBuffer) (A0.A1.D0) 

Bit Bit MapRast Port (srcbm,srcx,srcy,destrp,destX, 

destY,sizeX,sizeY,minter) (A0,D0,D1,A1,D2,D3,D4,D5,D6) 



icon. library 



$001E 


-30 


$0024 


-36 


$002A 


-42 


$0030 


-48 


$0036 


-54 


■$003C 


-60 


$0042 


-66 


$0048 


-72 


$004E 


-78 


$0054 


-84 


$005A 


-90 


$0060 


-96 


■$0066 


-102 


■$006C 


-108 



GetWBObject (name) (A0) 

PutWBObject (name, object) (A0,A1) 

Getlcon (name, icon, freelist) (A0,A1,A2) 

Putlcon (name, icon) (A0,A1) 

FreeFreeList (freelist) (A0) 

FreeWBObject (WBObject) (A0) 

AllocWBObject () 

AddFreeList (freelist, mem,size) (A0,A1,A2) 

GetDiskObject (name) (A0) 

PutDiskObject (name.diskob j ) (A0,A1) 

FreeDiskObj (diskobj) (A0) 

FindToolType (toolTypeArray,typeName) (A0,A1) 

MatchToolValue (typeString,value) (A0,A1) 

BumbRevision (newname.oldname) (A0,A1) 



intuition. library 



$001E 


-30 


$0024 


-36 


$002A 


-42 


$0030 


-48 


$0036 


-54 


$003C 


-60 


$0042 


-66 


$0048 


-72 


$004E 


-78 


$0054 


-84 


$005A 


-90 


$0060 


-96 


$0066 


-102 


$006C 


-108 


$0072 


-114 


$0078 


-120 



Openlntuition () 
Intuition (ievent) (A0) 

AddGadget (AddPtr,Gadget,Position) (A0,A1,D0) 
ClearDMRequest (Window) (A0) 
ClearMenuStrip (Window) (A0) 
ClearPointer (Window) (A0) 
CloseScreen (Screen) (A0) 
CloseWindow (Window) (A0) 
CloseWorkBench () 

CurrentTime (Seconds, Micros) (A0,A1) 
DisplayAlert (AlertNumber, String, Height ) (D0,A0,D1) 
DisplayBeep (Screen) (A0) 

Doubleclick (s seconds, smicros,cseconds,cmicros) 
(D0,D1,D2,D3) 

DrawBorder (Rport, Border, Lef tOf f set,TopOf f set ) 
(A0,A1,D0,D1) 

Drawlmage (RPort, Image, Lef tOf f set,TopOf f set ) 
(A0,A1,D0,D1) 
EndRequest (requester, window) (A0,A1) 
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GetDefPrefs (preferences, size) (AO,DO) 
GetPrefs (preferences, size) (AO,DO) 
InitRequester (req) (AO) 

ItemAddress (MenuStrip,MenuNumber) (A0,D0) 
ModifylDCMP (Window,Flags) (A0,D0) 
ModifyProp (Gadget,Ptr,Reg,Flags,HPos,VPos,HBody, 
VBody) (A0,A1,A2,D0,D1,D2,D3,D4) 
MoveScreen (Screen,dx,dy) (A0,D0,D1) 
MoveWindow (Window,dx,dy) (A0,D0,D1) 
Off Gadget (Gadget,Ptr,Req) (A0,A1,A2) 
OffMenu (Window,MenuNumber ) (A0,D0) 
OnGadget (Gadget,Ptr,Req) (A0,A1,A2) 
OnMenu (Window,MenuNumber) (A0,D0) 
OpenScreen (OSArgs) (AO) 
OpenWindow (OWArgs) (AO) 
OpenWorkBench () 

PrintlText (rp,itext, left, top) (A0,A1,D0,D1) 
RefreshGadgets (Gadgets,Ptr,Req) (A0,A1,A2) 
RemoveGadgets (RemPtr,Gadget) (A0,A1) 
ReportMouse (Window,Boolean) (A0,D0) 
Request (Requester,Window) (A0,A1) 
ScreenToBack (Screen) (AO) 
SCreenToFront (Screen) (AO) 
SetDMRequest (Window,req) (A0,A1) 
SetMenuStrip (Window,Menu) (A0,A1) 
SetPointer (Window,Pointer,Height,Width, XOf f set, 
YOffset) (A0,A1,D0,D1,D2,D3) 
-$0114 -276 SetWindowTitles (Window,windowTitle,screenTitle) 
(A0,A1,A2) 

ShowTitle (Screen,ShowIt ) (A0,D0) 
SizeWindow (Window,dx,dy) (A0,D0,D1) 
ViewAddress () 

ViewPortAddress (Window) (AO) 
WindowToBack (Window) (AO) 
WindowToFront (Window) (AO) 

WindowLimits (Window,minwidth,minheight,maxwidth, 
maxheight) (A0,D0,D1,D2,D3) 

SetPrefs (preferences, size, flag) (A0,D0,D1) 
IntuiTextLength (itext) (AO) 
WBenchToBack () 
WBenchToFront () 

AutoRequest (WIndow,Body,PText,NText,PFlag,NFlag,W,H) 
(A0,A1,A2,A3,D0,D1,D2,D3) 
BeginRefresh (Window) (AO) 

BuildSysRequest (Window,Body,Pos Text, NegText, Flags, 
W,H) ( A0,A1,A2,A3,D0,D1,D2 ) 
EndRefresh (Window,Complete) (A0,D0) 
FreeSysRequest (Window) (AO) 
MakeScreen (Screen) (AO) 
RemakeDisplay () 
RethinkDisplay () 

AllocRemember (RememberKey,Size,Flags) (AO,D0,Dl) 
AlohaWorkbench (wbport) (AO) 

FreeRemember (RememberKey,ReallyForget) (A0,D0) 
LocklBase (dontknow) (DO) 
UnlocklBase (IBLock) (AO) 



$007E 


-126 


$0084 


-132 


$008A 


-138 


$0090 


-144 


$0096 


-150 


$009C 


-156 


$00A2 


-162 


$00A8 


-168 


$00AE 


-174 


$00B4 


-180 


$00BA 


-186 


$00C0 


-192 


$00C6 


-198 


$00CC 


-204 


$00D2 


-210 


$00D8 


-216 


$00DE 


-222 


$00E4 


-228 


$00EA 


-234 


$00F0 


-240 


$00F6 


-246 


$00FC 


-252 


$0102 


-258 


$0108 


-264 


$010E 


-270 



$011A 


-282 


$0120 


-288 


$0126 


-294 


$012C 


-300 


$0132 


-306 


$0138 


-312 


$013E 


-318 


$0144 


-324 


$014A 


-330 


$0150 


-336 


$0156 


-342 


$015C 


-348 


$0162 


-354 


$0168 


-360 


$016E 


-366 


-$0174 


-372 


-$017A 


-378 


■$0180 


-384 


-$0186 


-390 


-$018C 


-396 


-$0192 


-402 


-$0198 


-408 


-$019E 


-414 


-$01A4 


-420 
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layers. library 

-$001E -30 InitLayers (li) (A0) 

-$0024 -36 CreateUpf rontLayer (li.bm.xO.yO.xl.yl.f lags,bm2) 

( A0,A1,D0,D1,D2,D3,D4,A2 ) 
-$002A -42 CreateBehindLayer (Ii,bm,x0,y0,xl,yl,f lags,bm2) 

(A0,A1,D0,D1,D2,D3,D4,A2 ) 

UpfrontLayer (li, layer) (A0,A1) 

BehindLayer (li, layer) (A0,A1) 

MoveLayer (li, layer, dx,dy) (A0,A1,D0,D1) 

SizeLayer (li, layer, dx,dy) ( A0,A1,D0,D1 ) 

ScrollLayer (li, layer, dx,dy) ( A0,A1,D0,D1) 

BeginUpdate (layer) (A0) 

EndUpdate (layer) (A0) 

DeleteLayer (li, layer) (A0,A1) 

LockLayer (li, layer) (A0,A1) 

UnlockLayer (li, layer) (A0,A1) 

LockLayers (li) (A0) 

UnlockLayers (li) (A0) 

LockLayerlnfo (li) (A0) 

SwapBitsRastPortClipRect (rp,cr) (A0,A1) 

WhichLayer (li,x,y) (A0,D0,D1) 

UnlockLayerlnfo (li) (A0) 

NewLayerlnfo () 

DisposeLayerlnfo (li) (A0) 

FattenLayerlnfo (li) (A0) 

ThinLayerlnfo (li) (A0) 

MoveLayer InFrontOf ( layer_to_move, 

layer_to_be_in_front_of ) (A0,A1) 



$0030 


-48 


$0036 


-54 


$003C 


-60 


$0042 


-66 


$0048 


-72 


$004E 


-78 


$0054 


-84 


$005A 


-90 


$0060 


-96 


$0066 


-102 


$006C 


-108 


$0072 


-114 


$0078 


-120 


$007E 


-126 


$0084 


-132 


$008A 


-138 


$0090 


-144 


■$0096 


-150 


■$009C 


-156 


$00A2 


-162 


■$00A8 


-168 



mathffp. library 



-$001E 


-30 


SPFix 


-$0024 


-36 


SPFlt 


-$002A 


-42 


SPCmp 


-$0030 


-48 


SPTst 


-$0036 


-54 


SPAbs 


-$003C 


-60 


SPNeg 


-$0042 


-66 


SPAdd 


-$0048 


-72 


SPSub 


-$004E 


-78 


SPMul 


-$0054 


-84 


SPDiv 



(float) (DO) 
(integer) (DO) 

(leftFloat.rightFloat) (D1,D0) 
(float) (Dl) 
(float) (DO) 
(float) (DO) 

(leftFloat,rightFloat) (D1,D0) 
(leftFloat.rightFloat) (D1,D0) 
(leftFloat.rightFloat) (D1,D0) 
(leftFloat.rightFloat) (D1,D0) 



math ieeedoubbas. library 



-$001E 


-30 


-$0024 


-36 


-$002A 


-42 


-$0030 


-48 


-$0036 


-54 


-$003C 


-60 



IEEEDPFix (integer, integer) (D0,D1) 

IEEEDPFlt (integer) (DO) 

IEEEDPCmp (integer, integer, integer, integer) 

(D0,D1,D2,D3) 

IEEEDPTst (integer, integer) (D0,D1) 

IEEEDPAbs (integer, integer) (D0,D1) 

IEEEDPNeg (integer, integer ) (D0,D1) 
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$0042 


-66 


$0048 


-72 


$004E 


-78 


$0054 


-84 



IEEEDPAdd (integer,integer,integer,integer ) 

(D0,D1,D2,D3) 

IEEEDPSub (integer, integer, integer, integer) 

(D0,D1,D2,D3) 

IEEEDPMul (integer, integer, integer, integer) 

(D0,D1,D2,D3) 

IEEEDPDiv (integer, integer, integer, integer) 

(D0,D1,D2,D3) 



mathtrans. library 



$001E 


-30 


$0024 


-36 


$002A 


-42 


$0030 


-48 


$0036 


-54 


$003C 


-60 


$0042 


-66 


$0048 


-72 


$004E 


-78 


$0054 


-84 


$005A 


-90 


$0060 


-96 


$0066 


-102 


■$006C 


-108 


$0072 


-114 


■$0078 


-120 


■$007E 


-126 



SPAtan (float) (DO) 

SPSin (float) (DO) 

SPCos (float) (DO) 

SPTan (float) (DO) 

SPSincos (leftFloat,rightFloat) (D1,D0) 

SPSinh (float) (DO) 

SPCosh (float) (DO) 

SPTanh (float) (DO) 

SPExp (float) (DO) 

SPLog (float) (DO) 

SPPow (leftFloat,rightFloat) (D1,D0) 

SPSqrt (float) (DO) 

SPTieee (float) (DO) 

SPFieee (float) (DO) 

SPAsin (float) (DO) 

SPAcos (float) (DO) 

SPLoglO (float) (DO) 



potgo. library 



-$0006 -6 AllocPotBits (bits) (DO) 
-$000C -12 FreePotBits (bits) (DO) 
-$0012 -18 WritePotgo (word,mask) (D0,D1) 



timer. library 



-$002A -42 
-$0030 -48 
-$0036 -54 



AddTime (dest,src) (A0,A1) 
SubTime (dest,src) (A0,A1) 
CmpTime (dest,src) (A0,A1) 



translator. library 



-$001E -30 Translate (inputString,inputLength,outputBuf f er, 

bufferSize) (A0,D0,A1,D1) 



247 



Appendix 



Amiga Machine Language 



Overview of MC68000 instructions 



Abbreviations (Symbols) used 



Label 

Reg 

An 

Dn 

Source 

Dest 

<ea> 

#n 



A label (address) 
Register 

Address register n 
Data register n 
Source operand 
Destination operand 
Address or Register 
Direct value 



Mnemonic 



ABCD 
ADD 
ADDA 
ADD I 
ADDQ 

ADDX 

AND 

AND I 

ASL 

ASR 

Bcc 

BCHG 

BCLR 

BRA 

BSET 

BSR 



BTST 

CHK 

CLR 

CMP 

CMPA 

CMP I 

CMPM 

DBcc 



Source J)est 
Source,Dest 
Source,An 
#n,<ea> 

#n,<ea> 

Source,Dest 

Source,Dest 

#n,<ea> 

n,<ea> 

n,<ea> 

Label 

#n,<ea> 

#n,<ea> 

Label 

#n,<ea> 

Label 



#n,<ea> 

<ea>J)x 

<ea> 

Source,Dest 

<ea>,An 

#n,<ea> 

Source,Dest 

Reg,Label 



Meaning 



DIVS Source JDest 



DIVU Source,Dest 



Addition of two BCD numbers 
Binary addition 

Binary addition to an address register 
Addition with a constant 
Fast addition of a constant which only needs 
bits to 7 

Addition with transfer to X flag 
Logical AND 

Logical AND with a constant 
Arithmetic shift left (*2 A n) 
Arithmetic shift right (/2*n) 
Branch depending on the condition 
Change bit n (0 becomes 1 and vice versa) 
Erase bit n 

Unconditional branch (similar to JMP) 
Set bit n 

Branch to a subroutine. The return address is 
put on the stack just like for the JSR com- 
mand. You return with a RTS command. 
Test bit n, the result goes in the Z flag 
Check a data register 
Erase an operand 
Compare two operands 
Compare with an address register 
Compare with a constant 
Compare two operands in memory 
Check condition, decrement and branch. This 
command is used with loops a lot. 
Sign correct division of a 32 bit destination 
operand by a 16 bit source operand. The result 
goes in the LO word of the destination long 
word. The remainder goes in the HI word. 
Division without sign, similar to DIVS 
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Mnemonic 


EOR 


Source,Dest 


EORI 


#n,<ea> 


EXG 


Rn,Rn 


EXT 


Dn 


JMP 


Label 


JSR 


Label 


LEA 


<ea>,An 


LINK 


An,#n 


LSL 


n,<ea> 


LSR 


n,<ea> 


MOVE 


Source,Dest 


MOVE 


SR,<ea> 


MOVE 


<ea>,SR 


MOVE 


<ea>,CCR 


MOVE 


USP,<ea> 


MOVE 


<ea>,USP 


MOVEA 


<ea>,An 


MOVEM 


Regs,<ea> 


MOVEM 


<ea>,Regs 


MOVEP 


Source,Dest 


MOVEQ 


#n,Dn 


MULS 


Source,Dest 


MULU 


Source,Dest 


NBCD 


Source,Dest 


NEG 


<ea> 


NEGX 


<ea> 


NOP 




NOT 


<ea> 


OR 


Source,Dest 


ORI 


#n,<ea> 


PEA 


<ea> 


RESET 




ROL 


n,<ea> 


ROR 


n,<ea> 


ROXL 


n,<ea> 


ROXR 


n,<ea> 


RTE 




RTR 




RTS 




SBCD 


Source,Dest 


Sec 


<ea> 


STOP 





Meaning 



Exclusive OR 

Exclusive OR with a constant 
Exchange the contents of two registers (don't 
mix this up with SWAP). 
Sign correct extension to double width 
Jump to an address (similar to BRA) 
Jump to a subroutine. The return address is put 
on the stack. A RTS returns to the command 
after this one. 

Load an effective address into An 
Build stack area 
Logical shift left 
Logical shift right 

Transfer a value from Source to Dest. 
Transfer the Status register contents 
Transfer the Status register contents 
Load flags 

Transfer the User Stackpointer 
Transfer the User Stackpointer 
Transfer a value to address register An 
Transfer several registers at the same time 
Transfer several registers at the same time 
Transfer data to peripheral devices 
Transfer a 8 bit constant to data register Dn 
quickly 

Sign correct multiplications of two words to a 
long word 

Multiplication without sign, similar to MULS 
Negate a BCD number (Nine's complement) 
Negate an operator (Two's complement) 
Negates an operator with transfer 
No Operation 

Inverts an operand (Os become Is and vice 
versa) 

Logical OR 

Logical OR with a constant 
Put an address on the stack 
Reset peripheral device (carefull!) 
Rotate left 
Rotate right 

Rotate left with transfer to X flag 
Rotate right with transfer to X flag 
Return from an Exception 
Return and load flags 

Return from a subroutine (after a BSR or JSR 
command) 

Subtract two BCD coded numbers 
Set a byte to -1 if the condition is fulfilled 
Stop work, (careful!) Leads to a TRAPV Ex- 
ception. 
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Mnemonic 



SUB 

SUBA 

SUB I 

SUBQ 

SUBX 

SWAP 

TAS 

TRAP 

TRAPV 

UNLK 



Source,Dest 

<ea>,An 

#n,<ea> 

#n,<ea> 

Source JDest 

Dn 

<ea> 

#n 



An 



Meaning 



Binary subtraction. 

Binary subtraction from an address register 

Subtract a constant. 

Fast subtraction of a three bit constant. 

Subtraction with transfer to X flag 

Exchange the two halves of the register (the 

upper and lower 16 bits) 

Test a bit and set bit 7 

Jump to an Exception 

Check if overflow flag set, then TST <ea>. 

Test an operand and set the N and Z flag 

Un-link stack area 
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absolute addressing 




20 


border structure 


202, 204 


absolute long 




24 


branch instructions 


30 


absolute long addressing 




20 


BSR 


23 


absolute short 




24 


bus error 


27, 233 


absolute short addressing. 




20 


byte 


5, 19 


address error 


27, 


233 






address register 




40 


Carry bit 


16 


address registerA7 




24 


carry clear 


31 


address register direct 


20 


,24 


carry set 


31 


address register indirect 


21 


,24 


character fonts 


102 


address register indirect with 16 bit 




character mode 


180 


displacement 




24 


character set 


167 


address register indirect with 8 bit index 


Chip RAM 


10 


value 




24 


CHK command 


233 


address register indirect with a 16 bit 




CHK instruction 


27,28 


displacement 




21 


chunks 


11 


address register indirect with an 8 bit 




CLI 


12, 143 


index 




21 


clist.library 


101 


address register indirect with post 






CloseLibrary 


163 


increment 


23 


,24 


CloseScreen 


169 


address register indirect with pre- 






CON 


108, 127 


decrement 


23 


,24 


conditional branch. 


30 


address registers 


15 


,24 


Condition codes 


30,31 


addressing 


19 


,24 


conditional operation 


30 


addressing types 




41 


console input/output 


108 


Agnus 




9 


console window 


102 


ALIGN 


19 


',50 


console.library 


102 


AllocAbs 




106 


control characters 


117 


AllocMem 




105 


Control register A 


96 


AmigaDOS 




108 


Control register B 


96 


arithmetic operations 




36 


Control Sequence Introducer 


118 


AssemPro 




50 


Copper lists 


101 


Audio Devices 




90 


custom chips 


9, 15 


AutoRequest 




179 


Custom screen 


167 


Axxx command emulation 




233 






Axxx-instruction emulation 


27 


r , 28 


Data direction register A 
Data direction register B 


96 
96 


BASIC 




3 


data register 


20 


Binary Coded Decimal 




37 


Data register A 


96 


binary system 




6 


Data register B 


96 


bit manipuation 




38 


data register direct 


20,24 


bit map 




177 


data registers 


15,24 


bit planes 




169 


debugger 


47, 50 


Blitter 




102 


decimal system 


6 


boolean gadget 




205 


Denise 


9 


border 




202 


device 


83 
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direct addressing, 20 

Direct Memory Access 90 

directory 143 

disk 152, 154 

disk drive 139 

diskfont.library 102 

DisplayBeep 172 
division by zero 27, 28, 233 

DMA control register 9 1 , 94 

dos.library 101 

DrawBorder 202 

EEROM 4 

egisters 15 

END 50 

EPROM 4 

equal 31 

EVEN 19, 50 

Event register 96 

events 182 

Examine 147 

Exception 231 

Exception routines 233 

Exceptions 26 

exec.library 101 

Execute 143 

false 31 

Fast RAM 10 

FIFO 16 

FilelnfoBlock 147, 152 

flags 41 

floating point operations. 102 

frequency 91 
Fxxx-instruction emulation 27, 28, 233 



gadget 

gadget structure 
gadget type 
gadgets 
GetMsg 
graphics. library 
greater or equal 
greater than 

handle 

handle number 
hardware registers 
hexadecimal system 
higher than 
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205, 208, 209 

208 

167 176 

182 

102 

31 

31 

109, 139 

113 

96 

7 

31 



icon.library 102 

icons 102 
IDCMP flag 174, 179, 182, 183 

Illegal command 233 

illegal instruction 27 

Image 199 
Image structure 200, 216 

indirect access 21 

indirect addressing 23 

interrupt 28 

Interrupt control register 96 

interrupt level 29 

Interrupt mask 17 

Interrupts 29 

Intuition 163 

Intuition Message Structure 183 

intuition.library 101 

joystick 98 

JSR 23 

keyboard input 122, 124 

Kickstart 4 

kilobyte 5 

layers.library 102 

less or equal 31 

less than 31 
level 1-7 interrupt 27, 28, 233 

libraries 101 

library functions 9 

LIFO 16 

List 144 

Lock 147 

logical operations 37 
long word 6, 19 

loudness level 91 

lower 31 

machine language 3 

macros 102 

masking 32 

math functions 102 

mathffp.library 102 

mathieeedoubbas.library 1 02 

math trans. library 102 

MC68000 15 
MC68000 instructions 34, 41 

MC68000 processor 3 

memcode 47 

memory map 10 
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Index 


menu item 


187 


program counter indirect with 8 bit index 


menu programming 


184 


value 


24 


menu structure 


184, 194 


program counter with 16 bit diplacement 


menu title 


185 




23 


menus 


101 


program counter with displacement 22 


message 


182 


Programs 


125, 148 


minus 


31 


adding numbers 


63 


mnenomic 


47 


ASCII to Decimal 


78 


mode 


109 


ASCII to HEX 


75 


mouse 


98 


Beep 


92 


move data 


40 


Control sequence output 


120 


multi-tasking 


10, 12 


converting numbers 


70 


music 


90 


Decimal to ASCII 


73 


narrator.device 


128 


Dir 


144 






Direct disk access 


152 


negative numbers 


6 


Disk Access 


157 


not equal 


31 


hex to ASCII 


70 


Number systems 


6 


Intuition Demo 


219 






joystick 


88 


object file 


48 


mouse 


86 


octal system 


7 


open window 


107 


offset 


103 


Open-Close window 


110 


OpenLib 


103 


OpenLib 


103 


OpenLibrary 


163 


Qpen and Move screen 


171 


OpenScreen 


165 


Sine wave 


92 


OpenWindow 


174 


Siren 


93 


operating system 


36 


Sort program 


67 


Overflow 


16 


sorting 


66 


Overflow clear 


31 


special keys 


84 


Overflow set 


31 


Speech 


128 






Talking program 


133 


Paula 


9,90 


Text output 


115 


PIA 


96 


timing 


85 


PIAA 


96 


PROM 


4 


PIAB 


96 


Proplnfo structure 


218 


pitch 


133 


Proportional gadget 


217 


PlaneOnOfT 


200 


Proportional gadgets 


216 


PlanePick 


200 


PRT 


127 


plus 


31 


pseudo-op 


19 


pointer 


103 






potentiometer. 


98 


RAM 


10,83 


potgo.library 


102 


RAM disk 


11 


printer 


127 


RAW 


111, 127 


PrintlText 


197 


registers 


5,83 


privilege 


26 


requester 


179 


privilege violation 


27, 28, 233 


RESET 




processor mode 


17 


starting PC 


27 


processor status 


16 


starting SSP 


27 


program counter 


15 


ROM 


4,83 


program counter indirect with 16 bit 


rotate 


38 


displacement 


24 


RTE 


233 
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Amiga Machine Language 



screen memory 




102 


TRAPV instruction 


27, 28, 233 


screen output 




112 


true 


31 


screen structure 


169, 


177 






screen table 




165 


Unassigned interrupt 


28 


screens 




101 


Unauthorized Interrupt 


233 


scrolling 




172 


Undo buffer 


213 


SEKA 




53 


uninitialized interrupt 


27, 28, 233 


SER 




128 


unjustified interrupt 


27 


Serial data register 




96 


user 


25 


serial interface 




128 


user byte 


16 


SetMenuStrip 




184 


User Interrupt vector 


233 


shift 




38 


user interrupt vectors 


27,29 


Smart-Refresh-Mode 




176 


user mode 


25 


sound chip 




90 


User port 


182 


Source 




48 


User stack 


232 


special keys 




84 


user stack pointer 


15, 232 


Speciallnfo pointer 




216 


UserState 


232 


Speciallnfo structure 




212 






speech 


132, 


133 


WaitForChar 


124 


speech synthesizer 




128 


window 


106 


square wave 




90 


window definition table 


174 


stack 


16,40 


window structure 


179, 182 


Stack Pointer 


16, 23 


windows 


101 


stack pointers 




15 


WOM 


5 


stacks 




24 


Wad 


19 


status register 


15, 16, 25, 29 


words 


6 


String gadget 
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Stringlnfo structure 


213, 


,214 






subroutines 




63 






Superstate 




232 






supervisor 




25 






supervisor bit 




25 






supervisor mode 


26, 35, 


,231 






Supervisor stack 




232 






symbol table 




56 






system byte 


16, 17 






system stack pointer 




15 






tasks 




12 






text structure 




179 






text structures 




180 






time slicing 




12 






Timer A HI 




96 






Timer A LO 




96 






Timer B HI 




96 






Timer B LO 




96 






timer.library 




102 






trace 


27, 


,233 






trace bit 




28 






translator.library 




102 






TRAP instructions 


27, 29,233 
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Companion Diskette 




For your convenience, the program listings contained in this book are 
available on an Amiga formatted floppy diskette. You should order the 
diskette if you want to use the programs, but don't want to type them in 
from the listings in the book. 

All programs on the diskette have been fully tested. You can change the 
programs for your particular needs. The diskette is available for $14.95 plus 
$2.00 ($5.00 foreign) for postage and handling. 

When ordering, please give your name and shipping address. Enclose a 
check, money order or credit card information. Mail your order to: 



Abacus Software 

5370 52nd Street SE 

Grand Rapids, MI 49512 

Or for fast service, call 616/698-0330. 
Credit Card orders only 1-800-451-4319. 
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Amiga for Beginners 



A perfect introductory book if you're a new or prospective Amiga owner. 

Amiga for Beginners 

introduces you to Intuition (the 

Amiga's graphic interface), the 

mouse, windows and the 

versatile CLI. This first volume 

in our Amiga series explains 

every practical aspect of the 

Amiga in plain English. Clear, 

step-by-step instructions for 

common Amiga tasks. Amiga 

for Beginners is all the info you 

need to get up and running. 

Topics include: 

• Unpacking and connecting 
the Amiga components 

• Starting up your Amiga 

• Exploring the Extras disk 

• Taking your first step in AmigaBASIC programming language 

• AmigaDOS functions 

• Customizing the Workbench 

• Using the CLI to perform "housekeeping" chores 

• First Aid, Keyword, Technical appendixes 

• Glossary 

Item #B021 ISBN 1-55755-021-2. Suggested retail price: $16.95 




Companion Diskette not available for this book. 



See your local dealer or order TOLL FREE 1-800-451-4319 in US & Canada 



Amiga BASIC: Inside and Out 



Amiga BASIC: Inside and Out is the definitive step-by-step guide to 

programming the Amiga in 

BASIC. This huge volume 

should be within every Amiga 

user's reach. Every Amiga 

BASIC command is fully 

described and detailed. In 

addition, Amiga BASIC: Inside 

and Out is loaded with real 

working programs. 

Topics include: 

• Video titling for high quality 
object animation 

• Bar and pie charts 

• Windows 

• Pull down menus 

• Mouse commands 

• Statistics 

• Sequential and relative files 

• Speech and sound synthesis 

Item #B87X ISBN 0-916439-87-9. Sugested retail price: $24.95 




Companion Diskette available: Contains every program listed in the 
book complete, error free and ready to run! Saves you hours of typing in 
program listings. Available only from Abacus. Item #S025. $14.95 



1 



See your local dealer or order TOLL FREE 1-800-451-4319 in US & Canada 



Amiga Machine Language 



Amiga Machine Language introduces you to 68000 machine language 

programming presented in 

clear, easy to understand 

terms. If you're a beginner, the 

introduction eases you into 

programming right away. If 

you're an advanced 

programmer, you'll discoverthe 

hidden powers of your Amiga. 

Learn how to access the 

hardware registers, use the 

Amiga libraries, create 

gadgets, work with Intuition and 

more. 

• 68000 microprocessor 
architecture 

• 68000 address modes and 
instruction set 

• Accessing RAM, operating 
system and multitasking capabilities 

• Details the powerful Amiga libraries for access to AmigaDOS 

• Simple number base conversions 

• Menu programming explained 

• Speech utility for remarkable human voice synthesis 

• Complete Intuition demonstration program including 
Proportional, Boolean and String gadgets 

Item #B025 ISBN 1-55755-025-5. Suggested retail price: $19.95 
Companion Diskette available: Contains every program listed in the 
book- complete, error free and ready to run! Saves you hours of typing in 
program listings. Available only from Abacus. Item #B025. $14.95 




See your local dealer or order TOLL FREE 1-800-451-4319 in US & Canada I 



Using ARexx on the Amiga 




Guide to using the ARexx 
programming language 



by Zamara and Sullivan 



Using ARexx on the Amiga is the most authoritative guide to using the 

popular ARexx programming 

language on the Amiga. It's 

filled with tutorials, examples, 

programming code and a 

complete reference section that 

you will use over and over 

again. Using ARexx on the 

Amiga is written for new users 

and advanced programmers 

of ARexx by noted Amiga 

experts Chris Zamara and Nick 

Sullivan. 



Topics include: 

• What is Rexx/ARexx - 
a short history 

• Thorough overview of all 
ARexx commands - with examples 

• Useful ARexx macros for controlling software and devices 

• How to access other Amiga applications with ARexx 

• Detailed ARexx programming examples for beginners and 
advanced users 

• Multi-tasking and inter-program communications 

• Companion diskette included 

• And much, much more! 




Item #B114 ISBN 1-55755-114-6. 
Suggested retail price: $34.95 
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Includes 

companion 

diskette 



See your local dealer or order TOLL FREE 1-800-451-4319 in US & Canada I 



AmigaDOS: Inside & Out Revised 




WORKBENCH 
1.3 & 2.0 



Inside & Out 

t&yteed 



An in-depth guide to 
AmigaDOS and the Shell 



AmigaDOS: Inside & Out covers the insides of AmigaDOS, everything 
from the internal design to practical applications. AmigaDOS Inside & Out 

will show you how to manage 
Amiga's multitasking capabilities 
more effectively. There is also a 
detailed reference section which 
helps you find information in a 
flash, both alphabetically and in 
command groups. Topics include 
getting the most from the 
AmigaDOS Shell (wildcards and 
command abbreviations) script 
(batch) files - what they are and 
how to write them. 

More topics include: 

• AmigaDOS - Tasks and 
handling 

• Detailed explanations of CLI 
commands and their functions 

• In-depth guide to ED and EDIT 

• Amiga devices and how the AmigaDOS Shell uses them 

• Customizing your own startup-sequence 

• AmigaDOS and multitasking 

• Writing your own AmigaDOS Shell commands in C 

• Reference for 1 .2, 1 .3 and 2.0 commands 

• Companion diskette included 

Item #B125 ISBN 1-55755-125-1. 
Suggested retail price: $24.95 
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Includes 

companion 

diskette 



See your local dealer or order TOLL FREE 1-800-451-4319 in US & Canada 



) 



Amiga C for Beginners 



Amiga C for Beginners is an introduction to learning the popular C 

language. Explains the 

language elements using 

examples specifically geared to 

the Amiga. Describes C library 

routines, howthe compiler works 

and more. 

Topics include: 

• Beginner's overview of C 

• Particulars of C 

• Writing your first program 

• The scope of the language 
(loops, conditions, functions, 
structures) 

• Special features of the 
C language 

• Input/Output using C 

• Tricks and Tips for 
finding errors 

• Introduction to direct programming of the operating system (windows, 
screens, direct text output, DOS functions) 

• Using the LATTICE and AZTEC C compilers 

Item #B045 ISBN 1 -55755-045-X. Suggested retail price: $19.95 

Companion Diskette available: Contains every program listed in the 
book- complete, error free and ready to run! Saves you hours of typing in 
program listings. Available only from Abacus. Item #S045. $14.95 




See your local dealer or order TOLL FREE 1-800-451-4319 in US & Canada I 



Amiga Graphics: Inside & Out 



Amiga Graphics: Inside & Out will show you the super graphic features 

and functions of the Amiga in 

detail. Learn the graphic 

features that can be accessed 

from AmigaBASIC or C. The 

advanced user will learn how to 

call the graphic routines from 

the Amiga's built-in graphic 

libraries. Learn graphic 

programming in C with 

examples of points, lines, 

rectangles, polygons, colors and 

more. Complete description of 

theAmigagraphicsystem-View, 

ViewPort, RastPort, bitmap 

mapping, screens and windows. 

Topics include: 

• Accessing fonts and type 
styles in AmigaBASIC 

• Loading and saving IFF graphics 

• CAD on a 1 024 x 1 024 super bitmap, using graphic 
library routines 

• Access libraries and chips from BASIC- 4096 colors at once, 
color patterns, screen and window dumps to printer 

• Amiga animation explained including sprites, bobs 
and AnimObs, Copper and blitter programming 

Item #B052 ISBN 1-55755-052-2. Suggested retail price: $34.95 
Companion Diskette available: Contains every program listed in the 
book- complete, error free and ready to run! Saves you hours of typing in 
program listings. Available only from Abacus. Item #S052. $14.95 




See your local dealer or order TOLL FREE 1-800-451-4319 in US & Canada j 



Amiga Desktop Video Power 



Includes 

Companion 

Diskette 



Amiga desktop Video Power is the most complete and useful guide to 
desktop video on the Amiga. 
Amiga Desktop Video Power 

covers all the basics- defining 
video terms, selecting 
genlocks, digitizers, scanners, 
VCRs, camera and connecting 
them to the Amiga. 



Just a few of the topics 
described in this excellent 
book: 




Desktop 
Power 



The most thorough guide 
to video on your Amiga 



Now includes DCTV, Video 

Toaster info 

The basics of video 

Genlocks 

Digitizers and scanners 

Frame Grabbers/ 

Frame Buffers 

How to connect VCRs,VTRs, and cameras to the Amiga 

Using the Amiga to add or incorporate Special Effects to a video 

Paint, Ray Tracing, and 3D rendering in commercial applications 

Animation 

Video Titling 

Music and videos 

Home videos 

Advanced techniques 




Item #B057 ISBN 1-55755-122-7 
Suggested retail price: $29.95 
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Includes 

companion 

diskette 



See your local dealer or order TOLL FREE 1-800-451-4319 in US & Canada I 



The Best Amiga Tricks & Tips 



The Best Amiga Tricks & Tips is a great collection of Workbench, CLI 
and BASIC programming "quick- 
hitters", hints and application 
programs. You'll be ableto make 
your programs more user- 
friendly with pull-down menus, 
sliders and tables. BASIC 
programmers will learn all about 
gadgets, windows, graphic 
fades, HAM mode, 3D graphics 
and more. 

The Best Amiga Tricks & Tips 

includes acomplete list of BASIC 
tokens and multitasking input 
and afast and easy print routine. 
If you're an advanced 
programmer, you'll discover the 
hidden powers of your Amiga. 

• Using the newAmigaDOS, Workbench and Preferences 1.3 
and Release 2.0 

• Tips on using the new utilities on Extras 1 .3 

• Customizing Kickstart for Amiga 1000 users 

• Enhancing BASIC using ColorCycle and mouse sleeper 

• Disabling FastRAM and disk drives 

• Using the mount command 

• Writing an Amiga virus killer program 

• Disk drive operations and disk commands 

• Learn machine language calls. 

Item # B107 ISBN 1-55755-107-3. 
Suggested retail price $29.95 



See your local dealer or order TOLL FREE 1-800-451-4319 in US & Canada 
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e for alt Amiga 
owners who want to tap all of the Amiga's 
true power using machine language. 
Amiga Machine Language is a 
combination of beginning tutorial and 
advanced programming guide all in oni 
book. 



Amiga Machine Language introduces 
you to 68000 machine language 
programming presented in clear, easy to 
understand terms. If you're a beginner, the 
introduction eases you into programming 
right away. If you're an advanced 
programmer, you'll discover the hidden 
powers of your Amiga. Learn how to 
access the hardware registers, use the 
Amiga libraries, create gadgets, work with 
Intuition and much more. 

Amiga Machine Language topics 
include: ■ opening windows • mouse 
functions • Working with Intuition • using 
requestors • creating screens and pull- 
down menus • all about gadgets * disk 
drive operations • disk commands ■ events 
• Supervisor mode • sound and tone 
generation 



ISBN 1-SS7SS-DES-S 




9 7 8l557"550255 



r ractical guide to 
learning 68000 
assembler language 
on the Amiga 



Many assembler programs presented, 
described and explained: 

• Simple number base conversions 

• Text input and output 

• Checking for special keys 

• Opening CON: T RAW: , SER: and PRT: 
devices. 

• New directory program that doesn't 
access the CLI 

• Menu programming explained 

• Speech utility for remarkable human 
voice synthesis 

• Complete Intuition demonstration 
program including Proportional, Boolean 
and String gadgets. 

Amiga Machine Language is an 

essential tutorial and reference book for all 
Amiga machine language programmers. 

Companion Program Diskette available: 

Contains every program listed in the book — 
complete, error-free and ready to run! Saves 
you hours of typing in machine language listings. 
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